Introduction - download.microsoft.comdownload.microsoft.com/.../Win7Changes-Audio.docx · Web viewThe Windows 7 HD Audio class driver opts out of idle detection for HD Audio codecs

Windows 7 Changes Related to Audio Drivers

March 15, 2010

Abstract

This paper highlights the new features and changes in Windows® 7 that impact audio device drivers. Developers who are updating audio device drivers to run on Windows 7 should read this paper.

Changes to the USB audio class driver for Windows 7 are also detailed in this paper. USB audio hardware vendors should read the “Changes to the Windows 7 USB Audio Class Driver” section of this paper.

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/audio/W7Changes-Audio.mspx.

The information presented in this paper might eventually be provided in the Windows Driver Kit (WDK). If you encounter a conflict between this paper and the WDK, consider the WDK to be factually correct and this paper to be out of date.

For further information, contact: [email protected]

Disclaimer: This document is provided “as-is”. Information and views expressed in this document, including URL and other Internet Web site references, may change without notice. You bear the risk of using it.

This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes.

© 2010 Microsoft Corporation. All rights reserved.

mailto:[email protected]

http://www.microsoft.com/whdc/device/audio/W7Changes-Audio.mspx

Windows 7 Changes Related to Audio Drivers - 2

Document HistoryDate ChangeMarch 15, 2010 First publication

ContentsIntroduction...................................................................................................................3Changes to Portcls.........................................................................................................3

New IPinName Interface...........................................................................................3New IPortWMIRegistration Interface.......................................................................6New PcUnregisterAdapterPowerManagement API Method..................................10New IPortClsPower Interface..................................................................................10New IAdapterPowerManagement2 Interface........................................................13New IPortClsSubdeviceEx Interface........................................................................15IDmaOperations Interface Removed......................................................................16

Driver INF Changes......................................................................................................17SetupPreferredAudioDevices Not Supported in Windows 7..................................17New PKEY_AudioDevice_NeverSetAsDefaultEndpoint Registry Key.......................17New PKEY_AudioDevice_EnableEndpointByDefault Registry Key...........................18New PKEY_ AudioEngine_OEMPeriod Registry Key.................................................20MSEP, MSFX for Inbox Audio Driver INF Files Only..................................................20

Changes to Kernel Streaming Properties.....................................................................21New KSPROPERTY_JACK_SINK_INFO Property........................................................21New KSPROPERTY_JACK_DESCRIPTION2 Property..................................................22Updated KSPROPERTY_PIN_PROPOSEDDATAFORMAT Property............................23

Dynamic Format Change Support................................................................................24WaveRT Pull Mode Support.........................................................................................27

Push Mode and Pull Mode Support in Windows Vista............................................27Changes to the Windows 7 USB Audio Class Driver.....................................................32

Runtime Idle Power Management Support.............................................................32Serial Copying Management System (SCSM) Copy Protection Support...................33Adjustable Isochronous Audio Capture Request Duration......................................33

Miscellaneous Driver Changes for Windows 7.............................................................34New WAVEFORMATEXTENSIBLE_IEC61937 Structure.............................................34New KSNodeType GUID for DisplayPort Audio........................................................34No HD Audio Bus Class Driver Interface Changes....................................................35Dynamic JACK Information Event............................................................................35Change to the CopyProtect member of the DRMRIGHTS Structure........................35

Resources....................................................................................................................36

March 15, 2010© 2010 Microsoft Corporation. All rights reserved.


IntroductionThis paper describes audio changes in Windows® 7 that impact audio device drivers. The goal of this paper is to help developers update their drivers for Windows 7 and its new features. It lists the possible changes to make to existing audio drivers and makes implementation suggestions for these changes to work with the related Windows 7 audio features. Audio requirements for the Windows 7 logo are described if they are appropriate.

This paper tries not to repeat information that is already provided in other articles or references such as MSDN®. Instead, it provides links between separate but related topics to make it easier to understand the changes.

Changes to PortclsIn Windows 7, the Portcls system driver (Portcls.sys) is updated with several changes. This section describes these changes and provides guidance for you to update your audio miniport driver.

New IPinName InterfaceThe IPinName interface was added to the Windows 7 Portcls system driver. Drivers that implement IPinName can dynamically update endpoint names.

In the Control Panel Sound application (mmsys.cpl), the following three strings describe an endpoint: Audio adaptor name

This string is the same as the device description string that is used in Device Manager for audio devices. An audio driver’s INF file provides the device description string, such as “Speakers”, “Headphones”, or “Microphone”. Some audio devices have an embedded friendly name. In this case, the client uses the friendly name that was retrieved from the device as the device’s device description string in Device Manager and as an endpoint’s audio adaptor name.

Endpoint stateThis string indicates the state of an endpoint, such as “Ready”, “Unplugged”, “Disabled”, or “Default Device”.

Endpoint nameThis is a description of the endpoint or physical audio device. This name is stored under the PKEY_Device_DeviceDesc endpoint property. Endpoint properties are located in the registry at:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\MMDevices\Audio\Render\%EndpointId%\Properties

In Windows Vista®, an endpoint’s name is static and is established when the endpoint is created. This name derives from the friendly name of the bridge pin of the underlying topology filter. If a system-defined KSNodeType GUID is specified for the pin, the string derives from ks.inf. Otherwise, the string derives from the audio driver INF if a proprietary KSNodeType is specified and defined in the audio driver package.



In Windows 7, the user mode audio (UMA) stack originates calls to the IPinName interface to retrieve the current endpoint name as follows: If your miniport driver supports IPinName, UMA uses the returned name as the

current endpoint name. If your miniport driver does not support IPinName, UMA uses the friendly name

of the topology pin based on KSNodeType.

Miniport drivers can use IPinName to dynamically customize endpoint names based on endpoint state or other conditions. The one exception in Windows 7 is that UMA explicitly does not let you customize the endpoint name for “Speakers” endpoints. That is, this interface works only on endpoints that are not “Speakers”.

In Windows 7, endpoints that are created from a topology bridge pin with any of the following KsNodeTypes are assigned the “Speakers” form factor: KSNODETYPE_SPEAKER KSNODETYPE_DESKTOP_SPEAKER KSNODETYPE_ROOM_SPEAKER KSNODETYPE_LOW_FREQUENCY_EFFECTS_SPEAKER

The HD Audio class driver uses the IPinName interface to dynamically update the High Definition Multimedia Interface (HDMI) endpoint name.

The following code shows the definition of the IPinName interface (from Portcls.h):DEFINE_GUID(IID_IPinName,0x29cc9ab1, 0xe89d, 0x413c, 0xb6, 0xb2, 0xf6, 0xd5, 0x0, 0x5, 0xd0, 0x63);/***************************************************************************** * IPinName, ***************************************************************************** * An OPTIONAL interface for miniports to implement to * enable them to get pin name from miniport driver */DECLARE_INTERFACE_(IPinName,IUnknown){ DEFINE_ABSTRACT_UNKNOWN() // For IUnknown

// Called by the port to notify registered miniports // for servicing verndor defined pin property // STDMETHOD_(NTSTATUS,GetPinName) ( THIS_ __in PIRP Irp, __in PKSP_PIN Pin, __out PVOID Data ) PURE;};

typedef IPinName *PIPINNAME;

#define IMP_IPinName \ STDMETHODIMP_(NTSTATUS) GetPinName \ ( __in PIRP Irp, \ __in PKSP_PIN Pin, \ __out PVOID Data \ );



The following is an implementation example of the IPinName interface:class CAzMixertopoMiniport :…public IMiniportTopology,public IPinName,…{…

IMP_IPinName;…}//------------------------------------------------------------------------------// Description://// Provide a way for the miniport to modify the pin name for a specific pin//// Parameters://// _PropReq - [in] Property Request containing request information for the// handler///// *****************************************************************************NTSTATUS CAzMixertopoMiniport::GetPinName( __in PIRP _pIrp, __in PKSP_PIN _pKsPPin, __out PVOID _pvData){ PAGED_CODE(); INIT_UNIQUE_PATH(); NTSTATUS status = STATUS_NOT_SUPPORTED; ULONG ulBufferLen = 0;

IF_NULL_ACTION_JUMP(_pIrp, status = STATUS_INVALID_PARAMETER, exit); IF_NULL_ACTION_JUMP(_pKsPPin, status = STATUS_INVALID_PARAMETER, exit); … ulBufferLen = IoGetCurrentIrpStackLocation(_pIrp)-> Parameters.DeviceIoControl.OutputBufferLength; // // Determine if this is just a query for the length of the // buffer needed, or a query for the actual data. // // TestName is defined as a constant to show an arbitary name // for demo purposes. You might want to dynamically change the // pin name when it’s needed. #define TestName L"My test pin name" if (!ulBufferLen) { // Return just the size of the string needed. _pIrp->IoStatus.Information = sizeof(TestName); status = STATUS_BUFFER_OVERFLOW; } else { RtlZeroMemory(_pvData, ulBufferLen); RtlCopyMemory((PVOID)_pvData, (PVOID)TestName, sizeof(TestName)); _pIrp->IoStatus.Information = sizeof(TestName); status = STATUS_SUCCESS;

}exit:… return status;}



The following screen shot shows how the Control Panel Sound application appears based on the preceding example code.

New IPortWMIRegistration InterfaceThe IPortWMIRegistration interface was added to the Windows 7 Portcls system driver. IPortWMIRegistration coordinates event registration between Portcls and the miniport adapter driver.

Event Tracing for Windows (ETW) is the system-supplied infrastructure that performs general-purpose, high-speed event tracing. Using a buffering and logging mechanism that is implemented in the kernel, ETW provides a tracing mechanism for events that are raised by both user-mode applications and kernel-mode device drivers. Additionally, ETW lets you dynamically enable and disable logging, which makes it easy to perform detailed tracing in production environments without requiring reboots or application restarts. For more information, see “Improve Debugging And Performance Tuning With ETW” on the MSDN Web site.

In Windows 7, Portcls implements some useful events, such as power state transitions and pin state changes. Such events can help you debug your audio driver code when they are interlaced with your miniport driver’s own ETW tracing. For device drivers, ETW control is through the IRP_MJ_SYSTEM_CONTROL dispatch entry. However, Portcls shares the same dispatch entry with portcls-based audio miniport drivers. Without a coordinated ETW registration mechanism between portcls and miniport drivers, one module might overwrite the other’s ETW registration. IPortWMIRegistration is added for achieving ETW registration coordination between portcls and the miniport adapter driver.



The following code shows the definition of the IPortWMIRegistration interface (from Portcls.h):DEFINE_GUID(IID_IPortWMIRegistration,0xd80b18e7, 0x804c, 0x4e1e, 0x82, 0xd3, 0x24, 0x61, 0xec, 0x6, 0xe7, 0xc7);

#define IMP_IPortWMIRegistration \ STDMETHODIMP_(NTSTATUS) RegisterWMIProvider \ ( IN PDEVICE_OBJECT _pDeviceObject, \ IN PVOID _pMiniPortWmiLibContext \ ) { return RegisterMiniportWMIProvider(_pDeviceObject,_pMiniPortWmiLibContext);};\ STDMETHODIMP_(NTSTATUS) UnregisterWMIProvider \ ( IN PDEVICE_OBJECT _pDeviceObject \ ) {return UnregisterMiniportWMIProvider(_pDeviceObject);};

/***************************************************************************** * IPortWMIRegistration *****************************************************************************/DECLARE_INTERFACE_(IPortWMIRegistration,IUnknown){ DEFINE_ABSTRACT_UNKNOWN() // For IUnknown

STDMETHOD_(NTSTATUS,RegisterWMIProvider) ( THIS_ PDEVICE_OBJECT, PVOID ) PURE; STDMETHOD_(NTSTATUS,UnregisterWMIProvider) ( THIS_ PDEVICE_OBJECT ) PURE;};

typedef IPortWMIRegistration *PPORTWMIREGISTRATION;

The following example code blocks show the various changes to make in your miniport driver to implement the IPortWMIRegistration interface:WMIGUIDREGINFO HDAudWmiGuidList[] ={ { &MiniPortDriverEvent_GUID, // define your own ETW GUID here 0, WMIREG_FLAG_TRACED_GUID | WMIREG_FLAG_TRACE_CONTROL_GUID // WMIREG_FLAG_TRACE_CONTROL_GUID is a required flag }, { &OtherMiniportEvent_GUID1, 1, WMIREG_FLAG_EVENT_ONLY_GUID }, { &OtherMiniportEvent_GUID2, 2, WMIREG_FLAG_EVENT_ONLY_GUID } ...};

//// Routine to check whether portcls supports WMIRegistration for driver// supporting multiple OS releases//BOOL IsPcWMIHelperSupported(){ NTSTATUS status = STATUS_UNSUCCESSFUL; PPORT pPort = 0; BOOL bRet = false;

PPORTWMIREGISTRATION pPortWMIRegistration = NULL;



status = PcNewPort (&pPort, CLSID_PortWaveCyclic); IF_FAILED_JUMP(status,exit);

status = pPort->QueryInterface(IID_IPortWMIRegistration, (PVOID *)&pPortWMIRegistration); IF_FAILED_JUMP(status,exit); pPortWMIRegistration->Release();exit: AE_SAFE_RELEASE(pPort); if (HD_SUCCESS (status)) { bRet = true; } return bRet;}

NTSTATUS DriverEntry(IN PDRIVER_OBJECT _pDriverObject, IN PUNICODE_STRING _pRegistryPath){ NTSTATUS status;… status = PcInitializeAdapterDriver(_pDriverObject, _pRegistryPath, AddDevice); IF_TRUE_ACTION_JUMP(!NT_SUCCESS(status), EOUT("Portclass failed to initialize the adapter driver!"),exit);

// Hook the port class unload function

_pDriverObject->DriverUnload = DriverUnload;… _pDriverObject->MajorFunction[IRP_MJ_PNP] = PnpHandler;

// Only declare dispatch routine for IRP_MJ_SYSTEM_CONTROL // when portcls does not support WMI helper routines if (!IsPcWMIHelperSupported()) { _pDriverObject->MajorFunction [IRP_MJ_SYSTEM_CONTROL] = HDAudioWmiSystemControl; }

…}

NTSTATUS PnpHandler(__in DEVICE_OBJECT *_Fdo, __in IRP *_Irp){ … stack = IoGetCurrentIrpStackLocation(_Irp); if ((IRP_MN_REMOVE_DEVICE == stack->MinorFunction) || (IRP_MN_SURPRISE_REMOVAL == stack->MinorFunction) || (IRP_MN_STOP_DEVICE == stack->MinorFunction)) {… status = HDAudUnregisterWmiProvider(_Fdo); // do some error handling and exit (omitted from sample code here)… } } status = PcDispatchIrp(_Fdo, _Irp);

exit:… return status;}



//// HDAudioWmiSystemControl handles WMI IRPs.//NTSTATUS HDAudioWmiSystemControl(__in PDEVICE_OBJECT _Fdo, __in PIRP Irp){ SYSCTL_IRP_DISPOSITION irpDisposition; NTSTATUS status = STATUS_SUCCESS; PortClassDeviceContext *ext= static_cast<PortClassDeviceContext*>(_Fdo->DeviceExtension);

IF_NULL_ACTION_JUMP(ext,status = STATUS_INVALID_DEVICE_REQUEST,exit); IF_NULL_ACTION_JUMP(ext->m_pWmiLibContext,status =

STATUS_INVALID_DEVICE_REQUEST,exit);

…

status = WmiSystemControl( ext->m_pWmiLibContext, _Fdo, Irp, &irpDisposition ); if (IrpProcessed != irpDisposition) { HDTrace(TRACE_LEVEL_ERROR, FLAG_INFO, "irpDisposition is not IrpProcessed"); } IF_FAILED_JUMP(status, exit); …exit: status = PcDispatchIrp(_Fdo, Irp); return status;}

NTSTATUS StartDevice(IN PDEVICE_OBJECT _Fdo, IN PIRP _Irp, IN PRESOURCELIST _ResourceList){… // // Register WMI provider // status = HDAudRegisterWmiProvider(_Fdo); IF_FAILED_JUMP(status,exit);

… return status;}

// HDAudRegisterWmiProvider registers the miniport’s ETW capability// with Portcls.//NTSTATUS HDAudRegisterWmiProvider(IN DEVICE_OBJECT *_Fdo){ NTSTATUS status = STATUS_UNSUCCESSFUL; PortClassDeviceContext *ext= static_cast<PortClassDeviceContext*> (_Fdo->DeviceExtension); PWMILIB_CONTEXT pWmiLibContext= NULL;

ext->m_pWmiLibContext = (PWMILIB_CONTEXT)ExAllocatePoolWithTag( NonPagedPool, sizeof(WMILIB_CONTEXT), 'MWdH' ); IF_NULL_ACTION_JUMP(ext->m_pWmiLibContext,status = STATUS_INSUFFICIENT_RESOURCES,exit); pWmiLibContext = ext->m_pWmiLibContext; RtlZeroMemory(pWmiLibContext, sizeof(WMILIB_CONTEXT));

pWmiLibContext->GuidCount = sizeof(HDAudWmiGuidList) / sizeof(WMIGUIDREGINFO); pWmiLibContext->GuidList = HDAudWmiGuidList; pWmiLibContext->QueryWmiRegInfo = HDAudWmiQueryRegInfo; pWmiLibContext->QueryWmiDataBlock = HDAudWmiQueryDataBlock; pWmiLibContext->SetWmiDataBlock = NULL; pWmiLibContext->SetWmiDataItem = NULL; pWmiLibContext->ExecuteWmiMethod = NULL;



pWmiLibContext->WmiFunctionControl = HDAudWmiFunctionControl;

status = WMIRegistrationWorker(_Fdo, pWmiLibContext, true);

exit: … return status;}

//HDAudUnregisterWmiProvider unregisters the previously registered// ETW interface.//NTSTATUS HDAudUnregisterWmiProvider (IN PDEVICE_OBJECT _Fdo){ NTSTATUS status = STATUS_UNSUCCESSFUL; PortClassDeviceContext *ext= static_cast<PortClassDeviceContext*>(_Fdo->DeviceExtension);

PAGED_CODE(); IF_NULL_ACTION_JUMP(ext,status = STATUS_INVALID_DEVICE_REQUEST,exit); IF_NULL_ACTION_JUMP(ext->m_pWmiLibContext,status = STATUS_INVALID_DEVICE_REQUEST,exit);

ExFreePool(ext->m_pWmiLibContext); ext->m_pWmiLibContext = NULL; status = WMIRegistrationWorker(_Fdo, NULL, false);

exit: return status;}

New PcUnregisterAdapterPowerManagement API MethodIn Windows 7, the PcUnregisterAdapterPowerManagement API method was added to PortCls.

For versions earlier than Windows 7, Portcls exports the PcRegisterAdapterPowerManagement API method for miniport drivers to register their power-management interfaces with PortCls. This enables miniport drivers to receive power state change events from PortCls. However, the miniport cannot notify Portcls to stop sending power events. If power state changes occur while an audio driver is unloading, Portcls calls IAdapterPowerManagement methods (such as PowerChangeState) to notify the driver of a power event. Depending on how far the driver‘s unloading process has progressed, some or all driver data structures that are referenced in these methods might already be invalid. This synchronization condition sometimes leads to a bugcheck that is difficult to reproduce. In Windows 7, PcUnregisterAdapterPowerManagement addresses this timing issue.

New IPortClsPower InterfaceThe IPortClsPower interface was added to the Windows 7 Portcls system driver. This interface makes it easier for drivers to support power management. IPortClsPower contains the following API methods:

RegisterAdapterPowerManagement registers the adapter’s power management interface with PortCls, which lets Portcls notify the adapter of power state change events.

SetIdlePowerManagement lets the miniport driver opt in or opt out of the PortCls idle power management.



UnregisterAdapterPowerManagement unregisters the adapter’s previously registered power management interface.

The Windows power manager provides support for idle detection. A device power policy owner is responsible for detecting when the device is in the idle state and can be put to sleep to conserve power. Portcls implements this idle detection in Windows Vista and Windows 7 for portcls-based audio miniport drivers that opt in for this support. The default setting is opted in.

Enabling idle detection saves power. However, when the device transitions power states, it can potentially cause pops if the hardware does not implement an anti-pop mechanism. The Windows 7 HD Audio class driver opts out of idle detection for HD Audio codecs that do not support the Intel HD Audio Low Power Capabilities Clarifications and Enhancements DCN HDA015-B because no standard way exists for a codec to handle eliminating audio pops. For more information about idle device detection, see “Detecting an Idle Device” on MSDN.

The following code shows the IPortClsPower interface definition from portcls.h:DEFINE_GUID(IID_IPortClsPower,0x47ba0351, 0xbc4b, 0x4869, 0x81, 0x34, 0xb7, 0x4f, 0xe1, 0x78, 0x52, 0xd8);

/***************************************************************************** * IPortClsPower ***************************************************************************** * Used to access the adapter power management functions. */DECLARE_INTERFACE_(IPortClsPower,IUnknown){ STDMETHOD_(NTSTATUS,RegisterAdapterPowerManagement) ( __in PUNKNOWN _pUnknown, __in PDEVICE_OBJECT _DeviceObject ) PURE; STDMETHOD_(NTSTATUS,UnregisterAdapterPowerManagement) ( __in PDEVICE_OBJECT _DeviceObject ) PURE; STDMETHOD_(NTSTATUS,SetIdlePowerManagement) ( __in PDEVICE_OBJECT _DeviceObject, __in BOOLEAN _bEnabled ) PURE;};

The following code example shows how to implement IPortClsPower in a miniport driver:// Register power management in the Start Device call.

NTSTATUS StartDevice(IN PDEVICE_OBJECT _Fdo, IN PIRP _Irp, IN PRESOURCELIST _ResourceList){… // Initialization of m_Common was successful; initialize m_Power interface status = CreateAzPower(&ext->m_Power, ext->m_Common); if (!HD_SUCCESS(status)) { AE_SAFE_DELETE(ext->m_Common); HDTrace(TRACE_LEVEL_ERROR, FLAG_INFO, "Failed to create the power object!"); JUMP(exit); }



HDTrace(TRACE_LEVEL_VERBOSE, FLAG_POWER, "Created power object"); status = RegisterPortClsPower(ext->m_Power, ext->m_Common, _Fdo); …exit:… return status;}//------------------------------------------------------------------------------// Description://// Determine whether the portcls class in the system running this driver// supports registering the adapter power management interface and// register it.//// Parameters://// _PowerUnk [in] - IUnknown Interface for AzPower.// _Common [in] - Pointer to the CAzCommon object.// _pDeviceObject [in] - Functional Device object pointer.//NTSTATUS RegisterPortClsPower(PUNKNOWN _PowerUnk, CAzCommon *_Common, PDEVICE_OBJECT _pDeviceObject){ PAGED_CODE();

NTSTATUS status = STATUS_UNSUCCESSFUL; PPORT pPort = NULL; PPORTCLSPOWER pPortClsPower = NULL;

…

status = PcNewPort(&pPort, CLSID_PortWaveCyclic); IF_FAILED_JUMP(status,no_interface);

status = pPort->QueryInterface(IID_IPortClsPower, (PVOID *)&pPortClsPower); IF_FAILED_JUMP(status,exit);

status = pPortClsPower->RegisterAdapterPowerManagement( _PowerUnk, _pDeviceObject); IF_FAILED_JUMP(status,exit);

exit: AE_SAFE_RELEASE(pPortClsPower); AE_SAFE_RELEASE(pPort);… return status;

no_interface: status = PcRegisterAdapterPowerManagement(_PowerUnk, _pDeviceObject); JUMP(exit);}//------------------------------------------------------------------------------// Description://// Determine whether the portcls class in the system running this driver// supports unregistering the adapter power management interface and// unregister it.//// Parameters://// _pDeviceObject [in] - Functional Device object pointer.//NTSTATUS UnregisterPortClsPower(PDEVICE_OBJECT _pDeviceObject){ PAGED_CODE(); INIT_UNIQUE_PATH();

NTSTATUS status = STATUS_UNSUCCESSFUL; PPORT pPort = NULL; PPORTCLSPOWER pPortClsPower = NULL;



…

status = PcNewPort (&pPort, CLSID_PortWaveCyclic); IF_FAILED_JUMP(status,exit);

status = pPort->QueryInterface (IID_IPortClsPower, (PVOID *)&pPortClsPower); IF_FAILED_JUMP(status, exit);

status = pPortClsPower->UnregisterAdapterPowerManagement(_pDeviceObject);

exit: AE_SAFE_RELEASE(pPortClsPower); AE_SAFE_RELEASE(pPort);… return status;

}

//NTSTATUS DriverEntry(IN PDRIVER_OBJECT _pDriverObject, IN PUNICODE_STRING _pRegistryPath){… _pDriverObject->MajorFunction[IRP_MJ_PNP] = PnpHandler;…}

NTSTATUS PnpHandler(__in DEVICE_OBJECT *_Fdo, __in IRP *_Irp){ … stack = IoGetCurrentIrpStackLocation(_Irp); if ((IRP_MN_REMOVE_DEVICE == stack->MinorFunction) || (IRP_MN_SURPRISE_REMOVAL == stack->MinorFunction) || (IRP_MN_STOP_DEVICE == stack->MinorFunction)) {…… UnregisterPortClsPower(_Fdo); AE_SAFE_RELEASE(ext->m_Power);… } } status = PcDispatchIrp(_Fdo, _Irp);exit:… return status;}

New IAdapterPowerManagement2 InterfaceIn Windows 7, the IAdapterPowerManagement2 interface was added to PortCls. This interface lets miniport drivers distinguish between runtime idle power transitions and system power transitions, which enables the miniport driver to determine the exact reason it is being told to enter lower power states.

The difference between IAdapterPowerManagement2::PowerChangeState2 and IAdapterPowerManagement::PowerChangeState is that SystemPowerState information is provided in the PowerChangeState2 call. You can use this information to decide whether to power down or disable certain hardware features when your miniport driver is told to go to the D3 power state. For example, if the D3 request results from device idle detection, the miniport driver might not disarm jack detection logic on its hardware.



If you implement and register both IAdapterPowerManagement2 and IAdapterPowerManagement, PortCls calls only IAdapterPowerManagement2::PowerChangeState2 for power state transitions. To register this interface, call PcRegisterAdapterPowerManagement (or IPortClsPower::RegisterAdapterPowerManagement).

For more information, see “IAdapterPowerManagement2” on MSDN.

The following code is the IAdapterPowerManagement2 interface definition from portcls.h:DEFINE_GUID(IID_IAdapterPowerManagement2,0xE0F92E5DL, 0x67F5, 0x48EE, 0xB5, 0x7A, 0x7D, 0x1E, 0x90, 0xC5, 0xF4, 0x3D);

/***************************************************************************** * IAdapterPowerManagement2 ***************************************************************************** * An interface that adapters should implement and register if they want * power management messages. Register this interface with PortCls via * the PcRegisterAdapterPowerManagement() call. * * NOTE: If you want to fill in the caps struct for your device, * register the interface with PortCls in or before your AddDevice() * function. The OS queries devices before StartDevice() gets called. */DECLARE_INTERFACE_(IAdapterPowerManagement2,IUnknown){ DEFINE_ABSTRACT_UNKNOWN() // For IUnknown DEFINE_ABSTRACT_ADAPTERPOWERMANAGEMENT()

// Called by PortCls to tell the device // to change to the new power state. // STDMETHOD_(void,PowerChangeState2) ( THIS_ __in DEVICE_POWER_STATE NewDeviceState, __in SYSTEM_POWER_STATE NewSystemState ) PURE;};

typedef IAdapterPowerManagement2 *PADAPTERPOWERMANAGEMENT2;

#define IMP_IAdapterPowerManagement2\ IMP_IAdapterPowerManagement;\ STDMETHODIMP_(void) PowerChangeState2\ ( __in DEVICE_POWER_STATE NewDeviceState,\ __in SYSTEM_POWER_STATE NewSystemState\ );\

The following code example shows how to implement IAdapterPowerManagement2 in a miniport driver:class AzPower :public IAdapterPowerManagement2,public CUnknown{…. IMP_IAdapterPowerManagement2; …};NTSTATUS AzPower::NonDelegatingQueryInterface(__in REFIID _Guid, __out PVOID *_Object){… if (IsEqualGUIDAligned(_Guid, IID_IUnknown)) { PATH_TRAP(); *_Object = this; }



else if (IsEqualGUIDAligned(_Guid, IID_IAdapterPowerManagement2)) { *_Object = this; } else if (IsEqualGUIDAligned(_Guid, IID_IAdapterPowerManagement)) { *_Object = this; } else { *_Object = NULL; }

if (*_Object) { static_cast<IUnknown*>(*_Object)->AddRef(); SET_STATUS_AND_JUMP(STATUS_SUCCESS, exit); } status = STATUS_INVALID_PARAMETER;exit:… return status;}////------------------------------------------------------------------------------// Description://// Implementation of IAdapterPowerManagement2::PowerChangeState2.// Interface method that causes a power state change.//// Parameters://// _NewDeviceState [in] - the device state to change to// _NewSystemState [in] - the current/new system power state//// Environment://// PASSIVE_LEVEL//// Return Values://// N/A//// Remarks://// This method cannot return an error code. If we fail to set the power state// we should try a second time or something to double check things.//STDMETHODIMP_(void) AzPower::PowerChangeState2(__in DEVICE_POWER_STATE _NewDeviceState, __in SYSTEM_POWER_STATE _NewSystemState){…

return;}

New IPortClsSubdeviceEx InterfaceIn Windows 7, the IPortClsSubdeviceEx::UpdatePinDescriptor interface was added to PortCls. Miniport drivers can call this interface to update the data ranges that are stored in their portcls subdevice pins whenever a format support change occurs. You must implement this interface if your miniport driver supports dynamic format change, which is described in “Dynamic Format Change Support” later in this paper.



A Portcls miniport driver reports its supported data ranges for each pin during the driver loading process. For editions earlier than Windows 7, miniport drivers have no way to update the reported data ranges after the driver is loaded. Some audio devices can support different format capabilities under different device configurations, such as sample rate knobs or switches on the audio devices. Without a way for the driver to dynamically update its reported data ranges, the driver must be unloaded and reloaded or the subdevice must be uninstantiated and re-instantiated. This resulted in a less desirable experience because existing streams that might still be supported with the new data ranges are interrupted. In Windows 7, IPortClsSubdeviceEx::UpdatePinDescriptor addresses this issue.

The following code shows the IPortClsSubdeviceEx interface definition from portcls.h:typedef IPortClsSubdeviceEx *PPORTCLSSubdeviceEx;

DEFINE_GUID(IID_IPortClsSubdeviceEx,0xc3d5e80c, 0x7f55, 0x40c5, 0x88, 0xb2, 0x62, 0x10, 0xd0, 0xcb, 0x2b, 0x59);

/***************************************************************************** * IPortClsSubdeviceEx ***************************************************************************** * Provide access to new subdevice registration APIs * PcRegisterSubdeviceEx and PcEnableSubDeviceInterfaces */DECLARE_INTERFACE_(IPortClsSubdeviceEx,IUnknown){ DEFINE_ABSTRACT_UNKNOWN() // For IUnknown

STDMETHOD_(NTSTATUS, UpdatePinDescriptor) ( __in ULONG _ulPinId, __in ULONG _ulFlags, __in PPCPIN_DESCRIPTOR _pPinDescriptor ) PURE;};

#define PCUPDATE_PIN_DESC_FLAG_DATARANGES 0x00000001

typedef IPortClsSubdeviceEx *PPORTCLSSubdeviceEx;

The following code example shows how to implement IPortClsSubdeviceEx in a miniport driver: PPORTCLSSubdeviceEx pPortClsSubdeviceEx = NULL; // PCPIN_DESCRIPTOR m_Desc; // PKSDATARANGE* ppNewDataRanges = NULL;

// update pin descriptor with new data range. m_Desc.KsPinDescriptor.DataRangesCount = ulNewDataRangesCount; m_Desc.KsPinDescriptor.DataRanges = ppNewDataRanges;

// Query for IPortClsSubdeviceEx interface status = m_pDevice->m_UnkWavePort->QueryInterface (IID_IPortClsSubdeviceEx, (PVOID *)&pPortClsSubdeviceEx); IF_FAILED_JUMP(status, exit);

// Give Portcls the new pin descriptor status = pPortClsSubdeviceEx->UpdatePinDescriptor(m_ulPinNumber, PCUPDATE_PIN_DESC_FLAG_DATARANGES, pDesc); IF_FAILED_JUMP(status, exit);



IDmaOperations Interface RemovedIn Windows 7, the IDmaOperations interface was removed from Portcls.h. Portcls never implemented this interface. Its removal is part of header file cleanup.

Driver INF ChangesThis section describes audio driver INF-related changes in Windows 7.

SetupPreferredAudioDevices Not Supported in Windows 7In Windows 7, the SetupPreferredAudioDevices keyword is not supported. To make default device selection more precise, default device settings are now completed at the endpoint level through default device heuristics. These heuristics are described in “Default Audio Endpoint Selection in Windows 7” on the WHDC Web site.

The SetupPreferredAudioDevices keyword is media-class specific and is supported only by Windows editions earlier than Windows 7. This keyword is included in a driver’s INF file to indicate that the endpoints that the driver exposed should become the default endpoints. Default endpoints are the devices that the audio system enables by default when the system contains one or more audio devices. SetupPreferredAudioDevices does not provide the same level of control as settings at the endpoint level because its declaration applies to all endpoints that are installed through the Install section, which makes its results unpredictable. That is, the endpoint that is chosen as the default depends on the unpredictable order in which the audio stack exposes and enumerates all endpoints.

New PKEY_AudioDevice_NeverSetAsDefaultEndpoint Registry KeySome device types—such as modem lines or medical audio devices—should never be set as a default device, even if no other audio devices exist on the system. In Windows 7, you can set the PKEY_AudioDevice_NeverSetAsDefaultEndpoint registry key in your driver INF file if you have such a device.

For your endpoint to declare its intention to be a default device, add the following code sample to your driver’s INF file:HKR,"EP\\n",%PKEY_AudioEndpoint_Association%,,%KSNODETYPE_GUID%HKR,"EP\\n", %PKEY_AudioDevice_NeverSetAsDefaultEndpoint%,0x00010001, NeverSetAsDefaultEndpointMaskValue

Where: PKEY_AudioEndpoint_Association is defined as "{1DA5D803-D492-4EDD-8C23-

E0C0FFEE7F0E},2". PKEY_AudioDevice_NeverSetAsDefaultEndpoint is defined as "{F3E80BEF-1723-

4FF2-BCC4-7F83DC5E46D4},3".

NeverSetAsDefaultEndpointMaskValue is a DWORD mask value from a combination of device roles (ROLE_MASK_CONSOLE, ROLE_MASK_COMMUNICATION, and ROLE_MASK_MULTIMEDIA) and data flows (FLOW_MASK_RENDER or FLOW_MASK_CAPTURE). This mask value is converted into the endpoint property store, and the audio stack uses this property to decide how to respond to default device queries and settings.



The following is an example INF entry:[MDVAD.EPProperties.AddReg]

;; set KSNODETYPE_OUTPUT_UNDEFINED to never be the default device for both;; console and communication roles on either render or capture categoriesHKR,"EP\\0",%PKEY_AudioDevice_NeverSetAsDefaultEndpoint %,,%KSNODETYPE_OUTPUT_UNDEFINED%HKR,"EP\\0",%PKEY_AudioDevice_SetDefaultEndpoint%,0x00010001,0x00000305;; 0x00000305à FLOW_MASK_RENDER | FLOW_MASK_CAPTURE | ROLE_MASK_CONSOLE | ROLE_MASK_COMMUNICATION [Strings]// Defines for new INF directivesKSNODETYPE_SPDIF_INTERFACE = "{DFF21FE5-F70F-11D0-B917-00A0C9223196}"PKEY_AudioEndpoint_Association = "{1DA5D803-D492-4EDD-8C23-E0C0FFEE7F0E},2"PKEY_AudioDevice_NeverSetAsDefaultEndpoint = "{F3E80BEF-1723-4FF2-BCC4-7F83DC5E46D4},3"

New PKEY_AudioDevice_EnableEndpointByDefault Registry KeyThe Windows 7 audio stack categorizes endpoints into form factors. These form factors are based on the KSNODETYPE GUID of a pin on the kernel streaming (KS) filter to which the endpoint is connected. For certain form factor types, the audio stack creates endpoints that are disabled and hidden. Users must manually go to the Control Panel Sound application to enable such an endpoint before it can be used. IHVs that want to override this behavior and have their endpoints created as enabled or disabled by default can use the new PKEY_AudioDevice_EnableEndpointBeDefault registry key.

The Windows 7 audio stack categorizes endpoints with any of the following KSNODETYPE values into the UnknownFormFactor form factor and creates them as hidden and disabled: KSNODETYPE_ANALOG_CONNECTOR KSCATEGORY_AUDIO KSNODETYPE_INPUT_UNDEFINED KSNODETYPE_OUTPUT_UNDEFINED KSNODETYPE_BIDIRECTIONAL_UNDEFINED KSNODETYPE_TELEPHONY_UNDEFINED KSNODETYPE_EXTERNAL_UNDEFINED KSNODETYPE_EMBEDDED_UNDEFINED KSNODETYPE_LEVEL_CALIBRATION_NOISE_SOURCE KSNODETYPE_EQUALIZATION_NOISE

In Windows 7, endpoints that have the LineLevel form factor but have a KSNODETYPE not equal to KSNODETYPE_LINE_CONNECTOR are also created as disabled and hidden. The following endpoints are in this category:

KSNODETYPE_LEGACY_AUDIO_CONNECTOR KSNODETYPE_1394_DA_STREAM KSNODETYPE_1394_DV_STREAM_SOUNDTRACK KSNODETYPE_CD_PLAYER KSNODETYPE_DAT_IO_DIGITAL_AUDIO_TAPE KSNODETYPE_DCC_IO_DIGITAL_COMPACT_CASSETTE KSNODETYPE_MINIDISK KSNODETYPE_PHONOGRAPH KSNODETYPE_ANALOG_TAPE



KSNODETYPE_VCR_AUDIO KSNODETYPE_VIDEO_DISC_AUDIO KSNODETYPE_DVD_AUDIO KSNODETYPE_TV_TUNER_AUDIO KSNODETYPE_SATELLITE_RECEIVER_AUDIO KSNODETYPE_CABLE_TUNER_AUDIO KSNODETYPE_DSS_AUDIO KSNODETYPE_RADIO_RECEIVER KSNODETYPE_RADIO_TRANSMITTER KSNODETYPE_MULTITRACK_RECORDER KSNODETYPE_SYNTHESIZER

To declare your endpoint as a potential default device, add the following information to your driver INF file:HKR,"EP\\n",%PKEY_AudioEndpoint_Association%,,%KSNODETYPE_GUID%HKR,"EP\\n", %PKEY_AudioDevice_EnableEndpointByDefault %,0x00010001, EnableEndpointByDefaultMaskValue

Where:

PKEY_AudioEndpoint_Association is defined as "{1DA5D803-D492-4EDD-8C23-E0C0FFEE7F0E},2".

PKEY_AudioDevice_EnableEndpointByDefault = "{F3E80BEF-1723-4FF2-BCC4-7F83DC5E46D4},4".

EnableEndpointByDefaultMaskValue is a DWORD mask value from a combination of the following flags:

FLAG_DISABLE (0x00000000) is used to force an endpoint to be set as disabled by default.

FLAG_ENABLE (0x00000001) is used to force an endpoint to be set as enabled by default.

When FLOW_MASK_RENDER (0x00000100) is set, the settings of disable/enable flag are applied if an endpoint is used as a RENDER endpoint.

When FLOW_MASK_CAPTURE (0x00000200) is set, the settings of the disable/enable flag are applied if an endpoint is used as a CAPTURE endpoint.

The following INF file excerpt shows how a CD player is set to be enabled by default and configured as an input device (FLOW_MASK_CAPTURE):[MDVAD.EPProperties.AddReg]

;; Enable by default for KSNODETYPE_CD_PLAYERHKR,"EP\\0",%PKEY_AudioEndpoint_Association%,,%KSNODETYPE_CD_PLAYER%HKR,"EP\\0",%PKEY_AudioDevice_EnableEndpointByDefault%,0x00010001,0x00000201;; 0x00000305à FLOW_MASK_CAPTURE | 0x00000001

[Strings]// Definitions for new INF directivesKSNODETYPE_CD_PLAYER = "{DFF220E3-F70F-11D0-B917-00A0C9223196}"PKEY_AudioEndpoint_Association = "{1DA5D803-D492-4EDD-8C23-E0C0FFEE7F0E},2"PKEY_AudioDevice_EnableEndpointByDefault = "{F3E80BEF-1723-4FF2-BCC4-7F83DC5E46D4},4"



New PKEY_ AudioEngine_OEMPeriod Registry KeyIn Windows 7, the audio engine runs at a 10-millisecond (ms) interval by default. You can customize this interval, which is named audio engine periodicity, by using the new PKEY_AudioEngine_OEMPeriod registry key in your audio driver INF file. The periodicity setting is a per-endpoint setting.

PKEY_AudioEngine_OEMPeriod is an INF directive that is used in the AddReg section of a device interface. The value in the following INF file example is specified as a VT_BLOB type. The valid periodicity range is 50,000 to 100,000 100-nanosecond units (50,000 to 100,000 hns or 5 to 10 ms) on even 10,000 HNSTIME unit boundaries (50,000, 60,000, 70,000, 80,000, 90,000, or 100,000 hns).

Although setting low periodicity helps reduce latency, it can also increase the chances of glitches. Be very careful about using low periodicity.

The following INF file example shows how to customize the periodicity for an audio driver: [USBAudio]Include=ks.inf, wdmaudio.inf, wdma_usb.infNeeds=KS.Registration, WDMAUDIO.Registration, USBAudio.CopyList, USBAudioOEM.AddReg

[USBAudio.Interfaces]AddInterface=%KSCATEGORY_AUDIO%,"GLOBAL",USBAudio.InterfaceAddInterface=%KSCATEGORY_RENDER%,"GLOBAL",USBAudio.Interface

[USBAudio.Interface]AddReg=USBAudio.Interface.AddReg, OEMSettingsOverride.AddReg

;;;; All EP\\0 entries in the same grouping;;;; Set default periodicity to 8ms;;;; On the line of PKEY_AudioEngine_OEMPeriod, 0x41 is used for VT_BLOB type.;; 8ms => 80000 (HNSTIME) => 0x013880 => load nibbles in reverse;; order as 80, 38, 01;;[OEMSettingsOverride.AddReg]HKR,"EP\\0", %PKEY_AudioEndpoint_Association%,,%KSNODETYPE_ANY%HKR,"EP\\0", %PKEY_AudioEngine_OEMPeriod%, %REG_BINARY%, 41,00,63,00,08,00,00,00,80,38,01,00,00,00,00,00

[Strings]

PKEY_AudioEndpoint_Association = "{1DA5D803-D492-4EDD-8C23-E0C0FFEE7F0E},2"PKEY_AudioEngine_OEMPeriod = "{E4870E26-3CC5-4CD2-BA46-CA0A9A70ED04},6"REG_BINARY = "0x00000001"

MSEP, MSFX for Inbox Audio Driver INF Files OnlyMSEP and MSFX are reserved audio INF directives only for inbox use. You can use the EP and FX directives in your Windows 7 driver INF files. As in Windows Vista, the EP and FX directives have a higher priority than MSEP and MSFX.



The following is an INF segment from HDAudio.inf:;Settings for endpoint property store;; Note: MSEP\\n is reserved for Microsoft inbox INF use ONLY.;; To avoid undeterministic results, 3rd party driver INFs should use EP\\n instead.[HDAudio.EPProperties.AddReg]HKR," EP\\0",%PKEY_AudioEndpoint_Association%,,%KSNODETYPE_ANY%// set the following key to 1 to opt inHKR," EP\\0",%PKEY_AudioEndpoint_Supports_EventDriven_Mode%,0x00010001,0x1

Changes to Kernel Streaming PropertiesThis section describes KS properties that are new or changed in Windows 7.

New KSPROPERTY_JACK_SINK_INFO PropertyThis KS property was added to Windows 7. It enables the driver to propagate HDMI sink information to its clients. Users can use the Control Panel Sound application to get property information for an HDMI endpoint.

The following example dialog box shows the supported formats of an HDMI device that the miniport reported through KSPROPERTY_JACK_SINK_INFO:

Like KSPROPERTY_JACK_DESCRIPTION, KSPROPERTY_JACK_SINK_INFO is a property on the topology filter pin under the KSPROPSETID_Jack property set. Only KSPROPERTY_TYPE_GET and KSPROPERTY_TYPE_BASICSUPPORT are supported for this property.



The KSPROPERTY_JACK_SINK_INFO property and its associated structures are defined in ksmedia.h. The following is the definition for KSJACK_SINK_INFORMATION, the structure in which the miniport reports the device’s information:typedef struct _tagKSJACK_SINK_INFORMATION{ KSJACK_SINK_CONNECTIONTYPE ConnType; // Connection Type WORD ManufacturerId; // Sink manufacturer ID WORD ProductId; // Sink product ID WORD AudioLatency; // Sink audio latency BOOL HDCPCapable; // HDCP Support BOOL AICapable; // ACP Packet, ISRC1, and ISRC2 Support UCHAR SinkDescriptionLength; // Monitor/Sink name length WCHAR SinkDescription[MAX_SINK_DESCRIPTION_NAME_LENGTH]; // Monitor/Sink name LUID PortId; // Video port identifier} KSJACK_SINK_INFORMATION, *PKSJACK_SINK_INFORMATION;

For more information, see “KSJACK_SINK_INFORMATION” on MSDN.

New KSPROPERTY_JACK_DESCRIPTION2 PropertyThe KSPROPERTY_JACK_DESCRIPTION2 property was added to Windows 7. You can use this property to report the state and jack-related capabilities of your audio device.

In Windows Vista, KSPROPERTY_JACK_DESCRIPTION was added to allow audio drivers to report the metadata that describes an audio jack. KSJACK_DESCRIPTION.IsConnected indicates whether an external device is connected to a jack. With this information alone, the audio stack cannot determine if a jack can detect whether a device is plugged in or unplugged. In Windows 7, whether an endpoint can detect a jack plays in important role when the system determines the priority of endpoint default settings. Therefore, correctly reporting jack detection is important. Miniport drivers can report this jack detection capability in Windows 7 by using KSPROPERTY_JACK_DESCRIPTION2.

Like KSPROPERTY_JACK_DESCRIPTION, KSPROPERTY_JACK_DESCRIPTION2 is a property on the topology filter pin under the KSPROPSETID_Jack property set. Only KSPROPERTY_TYPE_GET and KSPROPERTY_TYPE_BASICSUPPORT are supported for this property. For detailed information on this property, see “KSJACK_DESCRIPTION2” on MSDN.

When you implement the KSPROPERTY_JACK_DESCRIPTION2 property requests in your driver, remember the following requirements:

You cannot return just a KSJACK_DESCRIPTION2 structure for this request. A KSMULTIPLE_ITEM header is expected before KSJACK_DESCRIPTION2 structures, similar to the way in which KSJACK_DESCRIPTION is supported.

The Windows 7 audio stack incorrectly treats an endpoint that supports KSJACK_DESCRIPTION but not KSJACK_DESCRIPTION2 as capable of jack detection, which results in a less desirable user experience.

To earn a Windows 7 logo, an audio driver must support both the KSJACK_DESCRIPTION and KSJACK_DESCRIPTION2 properties.



Updated KSPROPERTY_PIN_PROPOSEDDATAFORMAT PropertyIn Windows 7, support for the PCPROPERTY_ITEM_FLAG_GET request type was added to KSPROPERTY_PIN_PROPOSEDDATAFORMAT. The Windows 7 audio stack sends KSPROPERTY_PIN_PROPOSEDDATAFORMAT with the PCPROPERTY_ITEM_FLAG_GET flag set to query a driver for its preferred device default format during audio endpoint creation.

KSPROPERTY_PIN_PROPOSEDDATAFORMAT is supported in Windows Vista and later editions. In Windows Vista, only the PCPROPERTY_ITEM_FLAG_SET flag is supported for querying whether a driver supports a particular format.

KSPROPERTY_PIN_PROPOSEDDATAFORMAT is a property on the Wave filter pin. For more details about this property, see “KSPROPERTY_PIN_PROPOSEDDATAFORMAT” on MSDN.

The following example code shows how you can update your miniport driver code to handle the PCPROPERTY_ITEM_FLAG_GET flag:NTSTATUS CMiniportHelper::PropertyHandlerPinProposeFormat( __inout PPCPROPERTY_REQUEST _pPropReq){… // // command basic support handling // if (_pPropReq->Verb & KSPROPERTY_TYPE_BASICSUPPORT) { // Validate buffer size if (!_pPropReq->ValueSize) { // ValueSize buffer too small _pPropReq->ValueSize = sizeof(ULONG); SET_STATUS_AND_JUMP(STATUS_BUFFER_OVERFLOW, exit); } else if (_pPropReq->ValueSize < sizeof (ULONG)) { SET_STATUS_AND_JUMP(STATUS_BUFFER_TOO_SMALL,exit); } else { // we have at least a ulong to work with so fill in access flags ULONG *accessFlags = static_cast<ULONG*>(_pPropReq->Value); *accessFlags = KSPROPERTY_TYPE_BASICSUPPORT | KSPROPERTY_TYPE_SET | KSPROPERTY_TYPE_GET; _pPropReq->ValueSize = sizeof(ULONG); SET_STATUS_AND_JUMP(STATUS_SUCCESS, exit); } } else if (_pPropReq->Verb & KSPROPERTY_TYPE_SET) { ULONG cbMinSize = sizeof(KSDATAFORMAT_WAVEFORMATEX);

… KSDATAFORMAT_WAVEFORMATEX *pKsFormat = (KSDATAFORMAT_WAVEFORMATEX*) _pPropReq->Value;

… // replace with your own format checking routine here. status = pDataPin->IsFormatSupported(&pKsFormat->WaveFormatEx);… } else if (_pPropReq->Verb & KSPROPERTY_TYPE_GET) { ULONG cbMinSize = sizeof(KSDATAFORMAT) + sizeof(WAVEFORMATEXTENSIBLE);

…



// Fill in the KSDATAFORMAT KSDATAFORMAT *pKsFormat = static_cast<KSDATAFORMAT*>(_pPropReq->Value); pKsFormat->FormatSize = sizeof(KSDATAFORMAT) + sizeof(WAVEFORMATEXTENSIBLE); pKsFormat->Flags = 0; pKsFormat->Reserved = 0; pKsFormat->SampleSize = 0; pKsFormat->MajorFormat = KSDATAFORMAT_TYPE_AUDIO; pKsFormat->SubFormat = KSDATAFORMAT_SUBTYPE_PCM; pKsFormat->Specifier = KSDATAFORMAT_SPECIFIER_WAVEFORMATEX;

// Fill in the Waveformat Extensible with preferred format parameters WAVEFORMATEXTENSIBLE *pWfx = reinterpret_cast<WAVEFORMATEXTENSIBLE*> (pKsFormat + 1); pWfx->Format.wFormatTag = WAVE_FORMAT_EXTENSIBLE; pWfx->Format.nChannels = static_cast<WORD>(numChannels); pWfx->Format.nSamplesPerSec = sampleRate; pWfx->Format.nBlockAlign = static_cast<WORD>(numChannels * (containerSize / 8)); pWfx->Format.nAvgBytesPerSec = sampleRate * pWfx->Format.nBlockAlign; pWfx->Format.wBitsPerSample = static_cast<WORD>(containerSize); pWfx->Format.cbSize = sizeof(WAVEFORMATEXTENSIBLE) - sizeof(WAVEFORMATEX); pWfx->SubFormat = KSDATAFORMAT_SUBTYPE_PCM; pWfx->Samples.wValidBitsPerSample = static_cast<WORD>(bitDepth); pWfx->dwChannelMask = channelMask; } else { … } …

exit: return status;}

Dynamic Format Change SupportDynamic format change is a new feature in Windows 7. This feature allows the format that is used to stream audio data between an audio application and an audio adapter to be changed dynamically. For editions earlier than Windows 7, after an audio driver is loaded, drivers cannot notify the audio stack that its format capabilities have changed and need to be reparsed unless the driver is unloaded and reloaded.

The following are some scenarios in which dynamic format change is used:

Some audio devices have hardware buttons or switches that a user can control to dynamically change the audio data format. In editions earlier than Windows 7, users are required to unload and reload the driver to get the new capabilities.

The supported formats that are available to an HDMI audio endpoint are related to the active display mode. Switching display modes on editions earlier than Windows 7 results in HDMI endpoints receiving an incorrect list of supported formats unless the driver is unloaded and reloaded.

System effects (SysFX) audio processing objects (APOs) that come with third-party driver packages might add new device formats such as AC3 in an encoding APO. For editions earlier than Windows 7, if this APO is disabled (most likely from the user interface), the lack of supported format change notification results in an incorrect supported format list.



In Windows 7, you can trigger the audio stack to re-evaluate a device’s format capabilities in two ways: The audio driver can initiate a KS event (KSEVENT) to notify the audio stack of a

device format capability change. To do so, use the KSEVENTSETID_PinCapsChange event set and its KSEVENT_PINCAPS_FORMATCHANGE event, which were added to Windows 7. For details, see “KSEVENT_PINCAPS_FORMATCHANGE” on MSDN.

The other way is through the IAudioEndpointFormatControl interface on the endpoint for multimedia device API (MMDevApi) applications. An MMDevApi client, such as an IHV’s APO, can call IAudioEndpointFormatControl::ResetToDefault on an endpoint to request the audio stack to re-evaluate the device format capabilities of an endpoint. For more details, see “IAudioEndpointFormatControl Interface” on MSDN.

The following is example code for a portcls-based miniport driver that uses a KSEVENT_PINCAPS_FORMATCHANGE event. Similar to the way in which volume events are defined and used for topology filters, format change events are defined and used on wave filters://Declare an event item for format change

static PCEVENT_ITEM PinFormatChangeEventTable[] ={ { &KSEVENTSETID_PinCapsChange, // Something on the pin changed! KSEVENT_PINCAPS_FORMATCHANGE, // Format changes KSEVENT_TYPE_ENABLE | KSEVENT_TYPE_BASICSUPPORT, WaveEventHandlerRT }};

// Create a automation table

DEFINE_PCAUTOMATION_TABLE_PROP_EVENT(WaveFilterAutomationTable, YourPropertiesWaveFilter, PinFormatChangeEventTable);

// Use this automation table in the wave filter

static PCFILTER_DESCRIPTOR MiniportFilterDescriptor ={ 0, // Version &WaveFilterAutomationTable, // AutomationTable sizeof(PCPIN_DESCRIPTOR), // PinSize SIZEOF_ARRAY(MiniportPins), // PinCount MiniportPins, // Pins sizeof(PCNODE_DESCRIPTOR), // NodeSize SIZEOF_ARRAY(MiniportNodes), // NodeCount MiniportNodes, // Nodes SIZEOF_ARRAY(MiniportConnections), // ConnectionCount MiniportConnections, // Connections 0, // CategoryCount NULL // Categories - use defaults (audio, render, capture)};

WaveEventHandlerRT(__in PPCEVENT_REQUEST _pEventRequest){ … switch (_pEventRequest->EventItem->Id) { case KSEVENT_PINCAPS_FORMATCHANGE: status = EventHandlerFormatChange(_pEventRequest); break; default:



… break; } … }

// This routine handles the event ADD and REMOVENTSTATUS EventHandlerFormatChange(__in PPCEVENT_REQUEST _pEventRequest){… switch (_pEventRequest->Verb) { case PCEVENT_VERB_SUPPORT: // BasicSupport Query for Event // break; case PCEVENT_VERB_ADD: // Adding Event // If we have the interface and EventEntry is defined ... if ((_pEventRequest->EventEntry) && m_pPortEvents) { m_pPortEvents->AddEventToEventList(_pEventRequest->EventEntry); } else { SET_STATUS_AND_JUMP(STATUS_UNSUCCESSFUL, exit); } break; case PCEVENT_VERB_REMOVE: // We cannot remove the event but we can stop generating the // events. However, it also doesn't hurt to always generate them ... // Removing Event … break; default: SET_STATUS_AND_JUMP(STATUS_INVALID_PARAMETER, exit); break; } status = STATUS_SUCCESS;exit:… return status;}

// Driver calls GenerateEventList to notify audio stack that supported// formats have been changed, which will cause format capability queries// from audio stack.

NTSTATUS CMiniportHelper::GenerateFormatChangeEvent(){ NTSTATUS ntStatus = STATUS_INVALID_DEVICE_REQUEST;

if (m_pPortEvents != NULL) { GUID gEventSet = KSEVENTSETID_PinCapsChange; m_pPortEvents->GenerateEventList(&gEventSet, // event set KSEVENT_PINCAPS_FORMATCHANGE, // event id TRUE, // this is a pin event PIN_NUMBER_ZERO, // pin id for the wave data pin FALSE, // not a node event ULONG(-1)); // an invalid node id ntStatus = STATUS_SUCCESS; } return ntStatus;}



The following example shows how an MMDevApi client can call IAudioEndpointFormatControl::ResetToDefault on an endpoint. CComPtr<IAudioEndpointFormatControl> spEndpointFormat;

hr = m_spEndpoint->Activate(__uuidof(IAudioEndpointFormatControl), CLSCTX_ALL, NULL, (void **)&spEndpointFormat); … hr = spEndpointFormat->ResetToDefault(0); …

WaveRT Pull Mode SupportThe Windows Vista and Windows 7 audio stacks support two streaming modes: push mode and pull mode. Pull mode (or event-driven mode) support is a Windows 7 logo requirement for WaveRT audio drivers. This section describes both modes and then provides implementation details to support pull mode in WaveRT driver for Windows 7.

Push Mode and Pull Mode Support in Windows VistaTo achieve smooth playback, WASAPI audio clients that run in push mode must repeatedly check the size of the available buffer to decide when to write data to or read data from an audio buffer. Audio clients that run in this mode tend to have longer latencies.

In pull mode, the audio engine sends a notification event upon audio buffer completion to indicate to the client that further data processing is required. This removes the need for the client to perform audio buffer polling and helps achieve lower latency. For details, see “IAudioClient::Initialize Method” on MSDN.

These two streaming modes are for interactions between audio clients and UMA. They also exist between UMA and audio device drivers and work similarly. In pull mode, the audio driver notifies UMA when the DMA engine of the audio hardware solution completes the audio buffer operation. UMA that runs with drivers that support pull mode can further reduce latency on behalf of WASAPI audio clients.

Most existing IHV audio WaveRT drivers support only push mode through their implementation of the IMiniportWaveRTStream interface. To support pull mode, these WaveRT drivers must implement the IMiniportWaveRTStreamNotification interface. This interface is defined in “A Wave Port Driver for Real-Time Audio Streaming” on the WHDC Web site. Assuming that your WaveRT driver already has push mode support and is running well in Windows Vista, make the following changes to your miniport driver code. Because most WaveRT drivers are for HD Audio codecs, the steps shown here apply to HD Audio solutions:



Use the HDAUDIO_BUS_INTERFACE_V2 structure instead of HDAUDIO_BUS_INTERFACE.This structure enables support for DMA completion notifications and is specific to HD Audio drivers. For more information about the HD audio bus interfaces, see “Microsoft Device Driver Interface for HD Audio” on WHDC.

The following is example miniport code://NTSTATUS AcquireAzBusInterface(HDAUDIO_BUS_INTERFACE *_pBusInt)NTSTATUS AcquireAzBusInterface(HDAUDIO_BUS_INTERFACE_V2 *_pBusInt){… // status = HDAllocate(sizeof(HDAUDIO_BUS_INTERFACE), status = HDAllocate(sizeof(HDAUDIO_BUS_INTERFACE_V2), gAzCommonAllocTag, FIXED_MEMORY|ZERO_FILL_MEMORY, (PVOID*)&m_BusInt); IF_FAILED_JUMP(status,exit);

irp = IoAllocateIrp (m_Fdo->StackSize, FALSE); IF_NULL_ACTION_JUMP(irp,status = STATUS_INSUFFICIENT_RESOURCES,exit);

irp->IoStatus.Status = STATUS_NOT_SUPPORTED; irp->IoStatus.Information = 0;

// Initialize the irp stack

PIO_STACK_LOCATION irpStack = IoGetNextIrpStackLocation(irp); irpStack->MajorFunction = IRP_MJ_PNP; irpStack->MinorFunction = IRP_MN_QUERY_INTERFACE; /*irpStack->Parameters.QueryInterface.InterfaceType= &GUID_HDAUDIO_BUS_INTERFACE; */ irpStack->Parameters.QueryInterface.InterfaceType = &GUID_HDAUDIO_BUS_INTERFACE_V2; irpStack->Parameters.QueryInterface.Version = 0x0100; irpStack->Parameters.QueryInterface.Size = sizeof(HDAUDIO_BUS_INTERFACE); irpStack->Parameters.QueryInterface.Size = sizeof(HDAUDIO_BUS_INTERFACE_V2); irpStack->Parameters.QueryInterface.Interface = reinterpret_cast<INTERFACE*>(_pBusInt); irpStack->Parameters.QueryInterface.InterfaceSpecificData = NULL;

// Submit the irp status = PcForwardIrpSynchronous(m_Fdo, irp); … IoFreeIrp( irp ); exit: … return status;}

Update your miniport stream object to inherit the IMiniportWaveRTStreamNotification interface (see the following example code): Replace IMiniportWaveRTStream inheritance with

IMiniportWaveRTStreamNotification. Add IMP_IMiniportWaveRTStreamNotification to the MiniportWaveRTStream

class.class CHdaMiniportWaveRTStream :…public IMiniportWaveRTStream,public IMiniportWaveRTStreamNotification…



{ … public: … IMP_IMiniportWaveRTStream; IMP_IMiniportWaveRTStreamNotification; …};

Add IID_IMiniportWaveRTStreamNotification support to the MiniportWaveRTStream NonDelegatingQueryInterface method.NTSTATUS CHdaMiniportWaveRTStream:: NonDelegatingQueryInterface(__in REFIID _Guid, __out PVOID *_Object){… if (IsEqualGUIDAligned(_Guid, IID_IUnknown)) { *_Object = (PVOID)(PMINIPORTWAVERTSTREAM)this; } else if (IsEqualGUIDAligned(_Guid, IID_IMiniportWaveRTStreamNotification)) { *_Object = (PVOID)(PMINIPORTWAVERTSTREAMNOTIFICATION)this; } else if (IsEqualGUIDAligned(_Guid, IID_IMiniportWaveRTStream)) { *_Object = (PVOID)(PMINIPORTWAVERTSTREAM)this; } … return status;}

Implement the following IMiniportWaveRTStreamNotification interface methods:

IMiniportWaveRTStreamNotification::AllocateBufferWithNotificationIMiniportWaveRTStreamNotification::FreeBufferWithNotificationIMiniportWaveRTStreamNotification::RegisterNotificationEventIMiniportWaveRTStreamNotification::UnregisterNotificationEvent

As you can see from the following example code, all four interface methods are primarily pass-through methods to the HD Audio bus driver interface:

//--------------------------------------------------------------------------// Description:// CHdaMiniportWaveRTStream::AllocateBufferWithNotification//// This function allocates audio ping pong buffers.//// Parameters://// RequestedSize - [in] Requested size.// AudioBufferMdl - [out] Filled with MDL on success.// ActualSize - [out] Filled with size on success.// OffsetFromFirstPage - [out] Filled with offset on success.// CacheType - [out] Filled with CacheType on success.//// Return Values://// NTSTATUS code.//NTSTATUS CHdaMiniportWaveRTStream::AllocateBufferWithNotification (IN ULONG NotificationCount, IN ULONG RequestedSize, __out PMDL *AudioBufferMdl, __out ULONG *ActualSize, __out ULONG *OffsetFromFirstPage, __out MEMORY_CACHING_TYPE *CacheType)



{ PAGED_CODE(); NTSTATUS status = STATUS_INVALID_PARAMETER;

// Validate that our output parameter pointers are non-NULL…

status = _pBusInt->AllocateDmaBufferWithNotification(_pBusInt->Context, m_hStreamHandle, NotificationCount, RequestedSize, &m_pBufferMdl, (SIZE_T*)&m_ulBufferLength, (SIZE_T*)OffsetFromFirstPage, &m_StreamId, &m_ulFifoSize);

IF_FAILED_ACTION_JUMP(status, DOUT(DBGErr, ("AllocateBufferWithNotification failed status=0x%08x", status)),exit);… // status is successful *AudioBufferMdl = m_pBufferMdl; *ActualSize = m_ulBufferLength; *CacheType = MmWriteCombined;exit: return status;}

//--------------------------------------------------------------------------// Description:// CHdaMiniportWaveRTStream::FreeBufferWithNotification//// This function frees the previously allocated audio buffer with// notification.//// Parameters://// Mdl - [in] Ignored.// Size - [in] Ignored.//// Return Values://// NTSTATUS code.//STDMETHODIMP_(VOID) CHdaMiniportWaveRTStream::FreeBufferWithNotification (IN PMDL BufferMdl, IN ULONG Size){… // Free the buffers… status = _pBusInt->FreeDmaBufferWithNotification(_pBusInt->Context, m_hStreamHandle, BufferMdl, (SIZE_T)Size);…exit: return;}

//--------------------------------------------------------------------------// Description:// CHdaMiniportWaveRTStream::RegisterNotificationEvent// This function registers the notification event.//// Parameters://// NotificationEvent - [in] The notification event.//STDMETHODIMP_(NTSTATUS) CHdaMiniportWaveRTStream::RegisterNotificationEvent (IN PKEVENT NotificationEvent)



{… IF_TRUE_ACTION_JUMP( !NotificationEvent, DOUT(DBGErr,("Null NotificationEvent pointer")); PATH_TRAP(), exit);… status = _pBusInt->RegisterNotificationEvent( _pBusInt->Context, m_hStreamHandle, NotificationEvent);…exit: return status;}

//--------------------------------------------------------------------------// Description:// CHdaMiniportWaveRTStream::UnregisterNotificationEvent//// This function unregisters the notification event.//// Parameters://// NotificationEvent - [in] The notification event.//// Return Values://// NTSTATUS code.//STDMETHODIMP_(NTSTATUS) CHdaMiniportWaveRTStream::UnregisterNotificationEvent (IN PKEVENT NotificationEvent){… IF_TRUE_ACTION_JUMP( !NotificationEvent, DOUT(DBGErr,("Null NotificationEvent pointer")); PATH_TRAP(),exit );… status = _pBusInt->UnregisterNotificationEvent(_pBusInt->Context, m_hStreamHandle, NotificationEvent); IF_FAILED_ACTION_JUMP(status,DOUT(DBGErr, ("UnregisterNotificationEvent failed status=0x%08x",status)), exit);…exit: return status;}

Opt in to pull mode support in the driver INF.

In Windows 7, pull mode support for an endpoint is disabled by default, even for WaveRT drivers that implement all the preceding required steps. To enable pull mode support, you must specifically opt in by setting the PKEY_AudioEndpoint_Supports_EventDriven_Mode property key in your INF file. UMA checks this key to determine whether to use pull mode. If you implement pull mode support in your Windows Vista WaveRT driver but do not appropriately set this INF key, your driver runs only in push mode on Windows 7.The following HD audio class driver INF file excerpt shows how to opt in to pull mode:AddInterface=%KSCATEGORY_TOPOLOGY%,%KSNAME_eSpeakerTopo%,HdAudModel.PrimarySpeakerTopo[HdAudModel.PrimarySpeakerTopo]AddReg = …, HDAudio.EPProperties.AddReg;Settings for endpoint property store;; Note: MSEP\\n is reserved for Microsoft inbox inf use ONLY.;; To avoid undeterministic result, 3rd party driver INF should;; use EP\\n instead.



[HDAudio.EPProperties.AddReg]HKR," EP\\0",%PKEY_AudioEndpoint_Association%,,%KSNODETYPE_ANY%// set the following key to 1 to opt inHKR," EP\\0",%PKEY_AudioEndpoint_Supports_EventDriven_Mode%,0x00010001,0x1[Strings]…PKEY_AudioEndpoint_Association = "{1DA5D803-D492-4EDD-8C23-E0C0FFEE7F0E},2"PKEY_AudioEndpoint_Supports_EventDriven_Mode = "{1DA5D803-D492-4EDD-8C23- E0C0FFEE7F0E},7"

Changes to the Windows 7 USB Audio Class DriverThe system-supplied Universal Serial Bus (USB) audio class driver evolved over the course of Windows 7 development. This section summarizes changes to the released driver’s operation, not including bug fixes. Note that this driver does not yet implement the USB Audio 2.0 Specification.

Runtime Idle Power Management SupportThe Windows 7 USB audio class driver implements runtime idle power management. This power-saving mechanism allows the system to power down the USB hub to which the device is attached. The USB audio class driver works with any USB audio device, not just those that have implemented Selective Suspend.

While the Windows 7 system is powered up, the driver is in a state that allows the device to be powered down due to inactivity to conserve power. The USB audio class driver tracks the streaming and property events and the time that the system most recently accessed these events. The driver uses the system’s built-in capability to set time-outs and send power events to set the activity timer based on the power policy of the system as follows: For power conservation mode, the driver sets the default ConservationIdleTime

value to 30 seconds. For performance mode, the driver sets the default PerformanceIdleTime value to

zero. A value of zero for performance mode effectively disables the idle timer for a performance-based power scheme. This value was chosen as the performance default because some devices have audible artifacts during power transitions.

For more information, see “Audio Device Class Inactivity Timer Implementation” on MSDN.

You can override the defaults by using a custom INF that allows your device to set the idle times as well as the device’s power state upon idle time-out. Add these entries to the AddReg section of the INF file for the device. The following is an example of the INF entries that set these values: [USBAudio.AddReg]…; 30 (0x1e) seconds for idle power management when on batteryHKR,PowerSettings,ConservationIdleTime,3,1e,00,00,0; Not doing idle power management when on AC powerHKR,PowerSettings,PerformanceIdleTime,3,00,00,00,00; go to D3 for idle power managementHKR,PowerSettings,IdlePowerState,3,03,00,00,00…

If no streaming or property request activity is detected in the time-out period, the system sends the designated low-power state change request to the driver. If the driver detects streaming activity or a property request while it is in the low-power



state, the driver requests a power state change to return to D0 to service the request. Streaming activity disables the timer and power state transitions as long as a streaming pin is opened and in use.

Serial Copying Management System (SCSM) Copy Protection SupportThe Windows 7 USB Audio Class Driver implements Serial Copy Management System (SCMS) copy protection on the device pins. Applications call the KSPROPERTY_DRMAUDIOSTREAM_CONTENTID property to determine if the pin can render protected. When a call to set this property occurs, the associated terminal unit receives a SET_CUR attribute on the COPY_PROTECT_CONTROL control selector with a level of CPL2 (0x02), the highest possible setting. For more details, see Section 5.2.2.1.3.1, “Copy Protect Control,” of the Universal Serial Bus Device Class Definition for Audio Devices Version 1.0 Specification. For more information on how this property works, see “KSPROPERTY_DRMAUDIOSTREAM_CONTENTID” on MSDN.

Adjustable Isochronous Audio Capture Request DurationIn Windows 7, you can adjust the duration of the request for isochronous audio capture.

In Windows Vista, the duration of the request for isochronous audio capture was hard-coded to 4 ms of data, down from 10 ms in Windows XP. This duration was decreased to reduce latency, especially for professional audio applications. However, it caused performance degradation on some systems because of the increased number of calls into, and time spent, at deferred procedure call (DPC) level to service the additional requests to the audio stack for the same amount of data.

For Windows 7 (and Windows Vista Service Pack 2), you can adjust the size of the request to the stack from the USB Audio driver in two ways: A device vendor can adjust the baseline value for the duration of the request

based on a registry entry in the AddReg section of an INF file that wraps the USB Audio class INF. Place an entry similar to the following in the wrapper INF: [USBAudio.AddReg]…; 8 millisecond data capture request defaultHKR, , CapturePacketsPerUrb,3,8,00,00,0

An application can override the capture request size by using the (set only) KSPROPERTY_AUDIO_BUFFER_DURATION property call to the pin. The following example shows how to use this call: KSPROPERTY ksProperty; ULONG cbProperty; ULONG ulBytesReturned; ULONG ulBufferDuration = x; // x == Buffer Duration in Milliseconds

// Initialize. cbProperty = sizeof(ksProperty);

// Fill the property structure. ZeroMemory(&ksProperty, cbProperty); ksProperty.Set = KSPROPSETID_AudioBufferDuration; ksProperty.Id = KSPROPERTY_AUDIO_BUFFER_DURATION; ksProperty.Flags = KSPROPERTY_TYPE_SET;

// Submit property request to driver



BOOL fRes = DeviceIoControl( hPinHandle, IOCTL_KS_PROPERTY, &ksProperty, cbProperty, &ulBufferDuration, Sizeof(ULONG), &ulBytesReturned, <pointer to initialized overlap structure> );

The KSPROPERTY_AUDIO_BUFFER_DURATION property call to the pin informs the driver of the period of the application. The driver should adjust its buffer size to match this value as closely as possible within a range of 3 to 10 ms. If the registry value is specified, it has precedence and overrides any attempt to set the value by using the property.

Miscellaneous Driver Changes for Windows 7This section describes various other changes to make in audio drivers for Windows 7.

New WAVEFORMATEXTENSIBLE_IEC61937 StructureIn Windows 7, WAVEFORMATEXTENSIBLE_IEC61937 was added to extend the existing WAVEFORMATEXTENSIBLE structure to store two sets of audio stream characteristics: The characteristics of the encoded audio format before transmission.

The characteristics of the audio stream after it has been decoded.

This new structure explicitly specifies the effective number of channels, sample size, and data rate of a format that is not in pulse code modulation (PCM). An application can use this information to infer the quality level of the non-PCM stream after it is decompressed and played.

For more information about this structure, see “Representing Formats for IEC61937 Transmissions” on MSDN.

The WAVEFORMATEXTENSIBLE_IEC61937 structure and a new list of GUIDs for standard IEC 61937–encoded audio formats were added to ksmedia.h. The following shows the structure definition:typedef struct { WAVEFORMATEXTENSIBLE FormatExt; // Format of encoded data as it is // intended to be streamed over the link DWORD dwEncodedSamplesPerSec; //Sampling rate of the post-decode audio. DWORD dwEncodedChannelCount; // Channel count of the post-decode audio. DWORD dwAverageBytesPerSec; // Byte rate of the content, can be 0.} WAVEFORMATEXTENSIBLE_IEC61937, *PWAVEFORMATEXTENSIBLE_IEC61937;

New KSNodeType GUID for DisplayPort AudioIn Windows 7, the GUID KSNODETYPE_DISPLAYPORT_INTERFACE was added to ksmedia.h. The following is its definition:#define STATIC_KSNODETYPE_DISPLAYPORT_INTERFACE\ 0xe47e4031, 0x3ea6, 0x418d, 0x8f, 0x9b, 0xb7, 0x38, 0x43, 0xcc, 0xba, 0x97DEFINE_GUIDSTRUCT("E47E4031-3EA6-418d-8F9B-B73843CCBA97", KSNODETYPE_DISPLAYPORT_INTERFACE);#define KSNODETYPE_DISPLAYPORT_INTERFACE DEFINE_GUIDNAMED(KSNODETYPE_DISPLAYPORT_INTERFACE)

The HD Audio class driver uses KSNODETYPE_DISPLAYPORT_INTERFACE as the KsNodeType of the bridge pin in the Topology filter for a DisplayPort Audio device.



No HD Audio Bus Class Driver Interface ChangesIn Windows 7, no interface changes to HDAudBus.sys were made.

Dynamic JACK Information EventIn Windows 7, a new KS event, KSEVENT_PINCAPS_JACKINFOCHANGE in the KSEVENTSETID_PinCapsChange event set, was added. Use KSEVENT_PINCAPS_JACKINFOCHANGE in your driver to notify UMA that the jack information values changed and must be queried again. UMA responds to this event by sending a KSPROPERTY_JACK_DESCRIPTION query to the driver. The usage of this event is very similar to that of KSEVENT_PINCAPS_FORMATCHANGE. The only difference is that KSEVENT_PINCAPS_JACKINFOCHANGE is on the Topology bridge pin whereas KSEVENT_PINCAPS_FORMATCHANGE is on the Wave Filter data pin. For an implementation sample, see “Dynamic Format Change Support” earlier in this paper.

Change to the CopyProtect member of the DRMRIGHTS StructureWindows Vista introduced protected user-mode audio (PUMA), the user-mode audio engine that runs in the protected environment (PE) that provides a safer environment for audio processing and rendering. PUMA allows only acceptable audio outputs to be enabled and ensures that outputs are reliably disabled. For more details about PUMA, see “Protected User Mode Audio (PUMA)” on MSDN.

PUMA has been updated for Windows 7 to provide support to: Set SCMS bits on S/PDIF endpoints. Your Windows 7 audio driver must ensure

that SCMS is set for S/PDIF output by setting the state to “Copy Never”. For S/PDIF interfaces, the driver validates that the combination of L, Cp, and Category Code bits indicates an SCMS state of “Copy Never”, as defined in IEC 60958.

Set High-Bandwidth Digital Content Protection (HDCP) bits on HDMI endpoints. A Windows 7 audio driver must ensure that the HDCP protection controls are set for HDMI output.

The protection control information is passed to your driver in the CopyProtect member of the DRMRIGHTS structure to support SCMS and HDCP protection. CopyProtect is not new to Windows 7. What has changed in Windows 7 is that this member can be specified by a client (application) and consumed by an audio driver. For more information about this structure, see “DRMRIGHTS” on MSDN.

If your driver supports both the DRMRIGHTS CopyProtect implementation and proprietary copy protection by using a private IoControl control, you must aggregate the protection from both sources when you decide what the combined protection setting should be.

The Windows 7 HD Audio class driver has been modified to support the “Copy Never” setting. The L is set to zero, and Category Code is always set to Digital Signal Mixer.

Exhibit B to the Windows Logo Program Testing Agreement has been updated to reflect the new expectations and requirements of a driver when CopyProtect is set.



Resources

Microsoft:

Microsoft Developer Network (MSDN)Audio Device Class Inactivity Timer Implementation

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

Detecting an Idle Devicehttp://msdn.microsoft.com/en-us/library/ms798268.aspx

DRMRIGHTShttp://msdn.microsoft.com/en-us/library/ms790085.aspx

IAdapterPowerManagement2http://msdn.microsoft.com/en-us/library/dd567939.aspx

IAudioEndpointFormatControl Interfacehttp://msdn.microsoft.com/en-us/library/dd408145(VS.85).aspx

IMiniportWaveRTStreamNotification::AllocateBufferWithNotificationhttp://msdn.microsoft.com/en-us/library/dd406687.aspx

IMiniportWaveRTStreamNotification::FreeBufferWithNotificationhttp://msdn.microsoft.com/en-us/library/dd406681.aspx

IMiniportWaveRTStreamNotification::RegisterNotificationEventhttp://msdn.microsoft.com/en-us/library/dd406685.aspx

IMiniportWaveRTStreamNotification::UnregisterNotificationEventhttp://msdn.microsoft.com/en-us/library/dd406714.aspx

Improve Debugging And Performance Tuning With ETWhttp://msdn.microsoft.com/en-us/magazine/cc163437.aspx

KSEVENT_PINCAPS_FORMATCHANGEhttp://msdn.microsoft.com/en-us/library/dd573912.aspx

KSJACK_DESCRIPTION2http://msdn.microsoft.com/en-us/library/dd573909.aspx

KSJACK_SINK_INFORMATIONhttp://msdn.microsoft.com/en-us/library/dd573916.aspx

KSPROPERTY_DRMAUDIOSTREAM_CONTENTIDhttp://msdn.microsoft.com/en-us/library/ms790179.aspx

KSPROPERTY_PIN_PROPOSEDDATAFORMAThttp://msdn.microsoft.com/en-us/library/ms808355.aspx

Protected User Mode Audio (PUMA)http://msdn.microsoft.com/en-us/library/dd756608(VS.85).aspx

Representing Formats for IEC61937 Transmissionshttp://msdn.microsoft.com/en-us/library/dd316761(VS.85).aspx


http://msdn.microsoft.com/en-us/library/dd316761(VS.85).aspx




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



http://msdn.microsoft.com/en-us/magazine/cc163437.aspx











WHDC Web siteDefault Audio Endpoint Selection in Windows 7

http://www.microsoft.com/whdc/resources/comingsoon.mspxA Wave Port Driver for Real-Time Audio Streaming

http://www.microsoft.com/whdc/device/audio/wavertport.mspxMicrosoft Device Driver Interface for HD Audio

http://www.microsoft.com/whdc/device/audio/hdaudioddi.mspx

Windows Quality (Winqual) Online Services Web siteExhibit B to the Windows Logo Program Testing Agreement

https://winqual.microsoft.com/member/LAC/DocumentDetails.aspx?id=1024&type=0

Specifications:

Intel:High Definition Audio Specification DCN HDA015-B: Low Power Capabilities Clarifications and Enhancements

http://www.intel.com/standards/hdaudio/

International Electrotechnical Commission (IEC):Digital Audio Interface – Part 3: Consumer Applications

http://www.iec.ch /index.html

USBUniversal Serial Bus Device Class Definition for Audio Devices Version 1.0 Specification

http://www.usb.org/developers/devclass_docs/audio10.pdf


http://www.usb.org/developers/devclass_docs/audio10.pdf

http://www.iec.ch/index.html

http://www.intel.com/standards/hdaudio/



http://www.microsoft.com/whdc/device/audio/hdaudioddi.mspx

http://www.microsoft.com/whdc/device/audio/wavertport.mspx

http://www.microsoft.com/whdc/resources/comingsoon.mspx

Documents

Introduction - download.microsoft.comdownload.microsoft.com/.../Win7Changes-Audio.docx · Web viewThe Windows 7 HD Audio class driver opts out of idle detection for HD Audio codecs