diff --git a/.acrolinx-config.edn b/.acrolinx-config.edn new file mode 100644 index 0000000000..043f6493b4 --- /dev/null +++ b/.acrolinx-config.edn @@ -0,0 +1,2 @@ +{:allowed-branchname-matches ["main" "release-.*"] + :allowed-filename-matches ["windows-driver-docs-pr"]} diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index 7e52eb22ba..0594813ffc 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -1,5 +1,30 @@ { "redirections": [ + { + "source_path": "windows-driver-docs-pr/wdf/using-i-o-targets.md", + "redirect_URL": "/windows-hardware/drivers/wdf/introduction-to-i-o-targets", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/wdf/hardware-resources-for-kmdf-drivers.md", + "redirect_URL": "/windows-hardware/drivers/wdf/introduction-to-hardware-resources", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/wdf/framework-queue-objects.md", + "redirect_URL": "/windows-hardware/drivers/wdf/creating-i-o-queues", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/wdf/framework-request-objects.md", + "redirect_URL": "/windows-hardware/drivers/wdf/creating-framework-request-objects", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/wdf/building--installing--and-testing-a-wdf-driver.md", + "redirect_URL": "/windows-hardware/drivers/wdf/building-and-loading-a-kmdf-driver", + "redirect_document_id": false + }, { "source_path": "windows-driver-docs-pr/kernel/processing-an-application-notification.md", "redirect_URL": "/windows-hardware/drivers/kernel/processing-wm_devicechange-messages", @@ -345,6 +370,21 @@ "redirect_URL": "/windows-hardware/drivers/bluetooth/testing-BTP-hw.md#supported-devices", "redirect_document_id": false }, + { + "source_path": "windows-driver-docs-pr/bluetooth/testing-BTP-setup.md", + "redirect_URL": "/windows-hardware/drivers/bluetooth/testing-BTP-Overview.md", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/bluetooth/bluetooth-profile-driver-functions.md", + "redirect_URL": "/windows-hardware/drivers/ddi/_bltooth/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/bluetooth/bluetooth-low-energy-functions.md", + "redirect_URL": "/windows/win32/api/_bltooth/", + "redirect_document_id": false + }, { "source_path": "windows-driver-docs-pr/dashboard/add-or-remove-drivers.md", "redirect_URL": "/windows-hardware/drivers/dashboard/manage-your-hardware-submissions", @@ -1512,6 +1552,11 @@ "redirect_URL": "windows-hardware/drivers/display/video-memory-management-and-gpu-scheduling", "redirect_document_id": false }, + { + "source_path": "windows-driver-docs-pr/display/ne-d3d10umddi-d3d10ddiresource_type.md", + "redirect_URL": "/windows-hardware/drivers/ddi/d3d10umddi/ne-d3d10umddi-d3d10ddiresource_type", + "redirect_document_id": false + }, { "source_path": "windows-driver-docs-pr/display/performing-copp-operations.md", "redirect_URL": "/windows-hardware/drivers/display/performing-copp-operations-example", @@ -4667,6 +4712,11 @@ "redirect_URL": "/previous-versions/windows/hardware/wireless/dsss--hrdsss--and-erp-phy-configuration", "redirect_document_id": false }, + { + "source_path": "windows-driver-docs-pr/network/dual-sim.md", + "redirect_URL": "/windows-hardware/drivers/network/mb-multi-sim-operations", + "redirect_document_id": false + }, { "source_path": "windows-driver-docs-pr/network/enabling-authentication-algorithms.md", "redirect_URL": "/previous-versions/windows/hardware/wireless/enabling-authentication-algorithms", @@ -6311,6 +6361,11 @@ "source_path": "windows-driver-docs-pr/network/offloading-the-segmentation-of-large-tcp-packets-in-ndis-6-0.md", "redirect_URL": "/previous-versions/windows/hardware/network/offloading-the-segmentation-of-large-tcp-packets-in-ndis-6-0", "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/network/oid-gen-supported-packet-filters.md", + "redirect_URL": "/windows-hardware/drivers/network/ntddndis-h", + "redirect_document_id": false }, { "source_path": "windows-driver-docs-pr/network/oid-dot11-active-phy-list.md", @@ -8382,6 +8437,11 @@ "redirect_URL": "/previous-versions/windows/hardware/wireless/wi-fi-network-list-offload", "redirect_document_id": false }, + { + "source_path": "windows-driver-docs-pr/network/wifi-universal-driver-model.md", + "redirect_URL": "/windows-hardware/drivers/network/wdi-miniport-driver-design-guide", + "redirect_document_id": false + }, { "source_path": "windows-driver-docs-pr/network/windot11-h.md", "redirect_URL": "/previous-versions/windows/hardware/wireless/windot11-h", @@ -8472,6 +8532,16 @@ "redirect_url": "/windows-hardware/drivers/sensors/common-sensor-properties", "redirect_document_id": false }, + { + "source_path": "windows-driver-docs-pr/sensors/overview-of-converged-sensor-driver-model.md", + "redirect_url": "/windows-hardware/drivers/sensors/index", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/sensors/testing-MALT-system-color.md", + "redirect_url": "/windows-hardware/drivers/sensors/testing-malt-system-brightness-and-color", + "redirect_document_id": false + }, { "source_path": "windows-driver-docs-pr/spb/testing-with-multi-interface-test-tool--mitt-.md", "redirect_url": "/windows-hardware/drivers/spb/multi-interface-test-tool--mitt--", @@ -8732,6 +8802,26 @@ "redirect_URL": "/windows-hardware/drivers/whea/how-to-manage-the-pfa-memory-list", "redirect_document_id": false }, + { + "source_path": "windows-driver-docs-pr/dashboard/bug-management.md", + "redirect_URL": "/collaborate/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/dashboard/pct-machines-wu-success-download.md", + "redirect_URL": "/windows-hardware/drivers/dashboard/pct-machines-where-driver-install-completes-successfully", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/dashboard/pct-machines-wu-success-install.md", + "redirect_URL": "/windows-hardware/drivers/dashboard/pct-machines-where-driver-install-completes-successfully", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/dashboard/percent-of-youtube-video-playback-failures-in-microsoft-edge-and-internet-explorer.md", + "redirect_URL": "/windows-hardware/drivers/dashboard/graphics-user-mode-crashes-edge-chromium-ecosystem", + "redirect_document_id": false + }, { "source_path": "windows-driver-docs-pr/dashboard/update-a-code-signing-certificate.md", "redirect_URL": "/windows-hardware/drivers/dashboard/code-signing-cert-manage", @@ -8811,7 +8901,881 @@ "source_path": "windows-driver-docs-pr/drivers/driversecurity/use-device-guard-readiness-tool.md", "redirect_URL": "/windows-hardware/drivers/driversecurity/implement-hvci-compatible-code", "redirect_document_id": false - } - - ] + }, + { + "source_path": "windows-driver-docs-pr/ifs/rxassert.md", + "redirect_URL": "/previous-versions/windows/hardware/rdbss/rxassert", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/ifs/rxdbgbreakpoint.md", + "redirect_URL": "/previous-versions/windows/hardware/rdbss/rxdbgbreakpoint", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/ifs/ccistheredirtyloggedpages.md", + "redirect_URL": "/windows-hardware/drivers/ddi/ntifs/index", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/ifs/ccsetloggeddatathreshold.md", + "redirect_URL": "/windows-hardware/drivers/ddi/ntifs/index", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/ifs/ccsetloghandleforfileex.md", + "redirect_URL": "/windows-hardware/drivers/ddi/ntifs/index", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/ifs/ccsetreadaheadgranularityex.md", + "redirect_URL": "/windows-hardware/drivers/ddi/ntifs/index", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/ifs/ccunmapfileoffsetfromsystemcache.md", + "redirect_URL": "/windows-hardware/drivers/ddi/ntifs/index", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/ifs/dual-oplock-key-ecp-context.md", + "redirect_URL": "/windows-hardware/drivers/ddi/ntifs/ns-ntifs-dual_oplock_key_ecp_context", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/ifs/exdisableresourceboost.md", + "redirect_URL": "/windows-hardware/drivers/ddi/ntifs/nf-ntifs-exdisableresourceboostlite", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/ifs/file-lock.md", + "redirect_URL": "/windows-hardware/drivers/ddi/ntifs/ns-ntifs-file_lock", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/ifs/keacquirequeuedspinlock.md", + "redirect_URL": "/windows-hardware/drivers/ddi/ntifs/nf-ntifs-keacquirequeuedspinlock", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/ifs/oplock-key-ecp-context.md", + "redirect_URL": "/windows-hardware/drivers/ddi/ntifs/ns-ntifs-oplock_key_ecp_context", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/ifs/pcomplete-lock-irp-routine.md", + "redirect_URL": "/windows-hardware/drivers/ddi/ntifs/nc-ntifs-pcomplete_lock_irp_routine", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/ifs/punlock-routine.md", + "redirect_URL": "/windows-hardware/drivers/ddi/ntifs/nc-ntifs-punlock_routine", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/ifs/fltacquireresourceexclusive.md", + "redirect_URL": "/windows-hardware/drivers/ddi/fltkernel/nf-fltkernel-fltacquireresourceexclusive", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/ifs/fltacquireresourceshared.md", + "redirect_URL": "/windows-hardware/drivers/ddi/fltkernel/nf-fltkernel-fltacquireresourceshared", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/ifs/fltreleaseresource.md", + "redirect_URL": "/windows-hardware/drivers/ddi/fltkernel/nf-fltkernel-fltreleaseresource", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/ifs/read-ahead-parameters.md", + "redirect_URL": "/windows-hardware/drivers/ddi/ntifs/ns-ntifs-read_ahead_parameters", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/ifs/nf-fltkernel-fltgetcopyinformationfromcallbackdata.md", + "redirect_URL": "/windows-hardware/drivers/ddi/fltkernel/nf-fltkernel-fltgetcopyinformationfromcallbackdata", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/ifs/nf-ntifs-iocheckfileobjectopenedascopydestination.md", + "redirect_URL": "/windows-hardware/drivers/ddi/ntifs/nf-ntifs-iocheckfileobjectopenedascopydestination", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/ifs/nf-ntifs-iocheckfileobjectopenedascopysource.md", + "redirect_URL": "/windows-hardware/drivers/ddi/ntifs/nf-ntifs-iocheckfileobjectopenedascopysource", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/ifs/ns-ntifs-copy_information.md", + "redirect_URL": "/windows-hardware/drivers/ddi/ntifs/ns-ntifs-copy_information", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/ifs/ns-ntifs-extended_create_information.md", + "redirect_URL": "/windows-hardware/drivers/ddi/wdm/ns-wdm-extended_create_information", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/ifs/wcifs-redirection-ecp-context.md", + "redirect_URL": "/windows-hardware/drivers/ddi/ntifs/ns-ntifs-create_redirection_ecp_context", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/debugging-oca-minidump-files.md", + "redirect_URL": "//windows-hardware/drivers/debugger/crash-dump-files", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/debugging-using-visual-studio.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/setting-up-user-mode-debugging-in-visual-studio.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/debugging-a-user-mode-process-using-visual-studio.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/opening-a-crash-dump-file-using-visual-studio.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/performing-kernel-mode-debugging-using-visual-studio.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/ending-a-debugging-session-in-visual-studio.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/setting-symbol-and-source-paths-in-visual-studio.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/remote-debugging-using-visual-studio.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/entering-debugger-commands-in-visual-studio.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/setting-breakpoints-in-visual-studio.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/viewing-the-call-stack-in-visual-studio.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/viewing-source-and-assembly-code-in-visual-studio.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/viewing-memory--variables--and-registers-in-visual-studio.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/viewing-threads-and-processes-in-visual-studio.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/configuring-exceptions-and-events-in-visual-studio.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/keeping-a-log-file-in-visual-studio.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/setting-up-kernel-mode-debugging-in-visual-studio.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/setting-up-a-network-debugging-connection-in-visual-studio.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/setting-up-a-1394-cable-connection-in-visual-studio.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/setting-up-a-usb-3-0-cable-connection-in-visual-studio.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/setting-up-a-usb-2-0-cable-connection-in-visual-studio.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/setting-up-a-null-modem-cable-connection-in-visual-studio.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/setting-up-kernel-mode-debugging-using-serial-over-usb-in-visual-studio.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/setting-up-a-connection-to-a-virtual-machine-in-visual-studio.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/window-menu.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/window---close-all-source-windows.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/window---close-all-error-windows.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/window---open-dock.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/window---dock-all.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/window---undock-all.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/window---mdi-emulation.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/window---automatically-open-disassembly.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/list-of-open-windows.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/help-menu.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/help---contents.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/help---index.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/help---search.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/help---about.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/view-menu.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/view---command.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/view---watch.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/view---locals.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/view---registers.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/view---memory.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/view---call-stack.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/view---disassembly.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/view---scratch-pad.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/view---processes-and-threads.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/view---command-browser.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/view---verbose-output.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/view---show-version.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/view---toolbar.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/view---status-bar.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/view---font.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/view---options.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/view---source-language-file-extensions.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/view---windbg-command-line.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/file-menu.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/file---open-source-file.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/file---close-current-window.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/file---open-executable.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/file---attach-to-a-process.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/file---open-crash-dump.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/file---connect-to-remote-session.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/file---connect-to-remote-stub.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/file---kernel-debug.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/file---symbol-file-path.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/file---source-file-path.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/file---image-file-path.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/file---open-workspace.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/file---save-workspace.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/file---save-workspace-as.md", + "redirect_URL": "//windows-hardware/drivers/debugger/file---clear-workspace.md", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/file---delete-workspaces.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/file---open-workspace-in-file.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/file---save-workspace-to-file.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/file---map-network-drive.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/file---disconnect-network-drive.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/file---recent-files.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/file---exit.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/edit-menu.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/edit---cut.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/edit---copy.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/edit---paste.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/edit---select-all.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/edit---write-window-text-to-file.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/edit---add-to-command-output.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/edit---clear-command-output.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/edit---evaluate-selection.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/edit---display-selected-type.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/edit---find.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/edit---find-next.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/edit---go-to-address.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/edit---go-to-line.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/edit---go-to-current-instruction.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/edit---set-current-instruction.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/edit---breakpoints.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/edit---open-clse-log-file.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/debug-menu.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/debug---go.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/debug---break.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/debug---restart.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/debug---go-unhandled-exception.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/debug---go-handled-exception.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/debug---stop-debugging.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/debug---detach-debuggee.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/debug---step-into.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/debug---step-over.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/debug---step-out.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/debug---run-to-cursor.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/debug---source-mode.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/debug---resolve-unqualified-symbols.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/debug---event-filters.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/debug---modules.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/debug---kernel-connection---cycle-baud-rate.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/debug---kernel-connection---cycle-initial-break.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/debug---kernel-connection---resynchronize.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/using-debugging-information-windows.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/opening-a-window.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/closing-a-window.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/configuring-a-window.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/moving-through-a-window.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/cutting-and-pasting-text.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/changing-text-properties.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/positioning-the-windows.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/debugging-with-floating-and-docked-windows.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/docking-a-window.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/tabbing-a-window.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/undocking-a-window.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/creating-a-new-dock.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/resizing-and-moving-a-window.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/windbg-graphical-interface-features.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/the-debugger-command-window.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/debugging-tools-for-windows--what-s-new.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/devtest/computerhardwareids-output.md", + "redirect_URL": "//windows-hardware/drivers/devtest/computerhardwareids", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/devtest/computerhardwareids-overview.md", + "redirect_URL": "//windows-hardware/drivers/devtest/computerhardwareids", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/symsrv.md", + "redirect_URL": "//windows-hardware/drivers/debugger/symbols", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/debugging-using-windbg-preview.md", + "redirect_URL": "//windows-hardware/drivers/debugger/windbg-overview", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/windbg-what-is-new-preview.md", + "redirect_URL": "//windows-hardware/drivers/debugger/windbg-release-notes", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/arranging-windows.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, { + "source_path": "windows-driver-docs-pr/debugger/edit---open-close-log-file.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/windbg-install-preview.md", + "redirect_URL": "//windows-hardware/drivers/debugger/", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/audio/acx-audio-multi-stack.md", + "redirect_URL": "//windows-hardware/drivers/audio/acx-multi-stack", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/audio/bluetooth-bypass-ddi-reference.md", + "redirect_URL": "//windows-hardware/drivers/audio/bluetooth-bypass-guidelines-for-audio-drivers", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/audio/btth-architectural-overview.md", + "redirect_URL": "//windows-hardware/drivers/audio/bluetooth-bypass-guidelines-for-audio-drivers", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/audio/management-of-i2s-and-sco-resources.md", + "redirect_URL": "//windows-hardware/drivers/audio/bluetooth-bypass-guidelines-for-audio-drivers", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/audio/related-design-guidelines.md", + "redirect_URL": "//windows-hardware/drivers/audio/bluetooth-bypass-guidelines-for-audio-drivers", + "redirect_document_id": false + }, + + { + "source_path": "windows-driver-docs-pr/audio/theory-of-operation.md", + "redirect_URL": "//windows-hardware/drivers/audio/bluetooth-hfp-bypass-audio-streaming", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/mobilebroadband/hotspot-20.md", + "redirect_URL": "//windows-hardware/drivers/mobilebroadband/passpoint", + "redirect_document_id": false + }, + { + "source_path": "windows-driver-docs-pr/debugger/source-code.md", + "redirect_URL": "//windows-hardware/drivers/debugger/source-path", + "redirect_document_id": false + } + ] } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1a8b3bc716..a56bf256ac 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,7 +16,7 @@ If you've already contributed to Microsoft repositories in the past, congratulat If you'd like to suggest a change to the docs, follow these steps: -1. While viewing a published article in [Windows hardware developer documentation](https://docs.microsoft.com/windows-hardware/drivers/), click the **Edit** button in the upper right of the page. You will be redirected to the corresponding Markdown source file in the [GitHub repository](https://github.com/MicrosoftDocs/windows-driver-docs). If you're already in the [GitHub repo](https://github.com/MicrosoftDocs/windows-driver-docs), you can just navigate to the source file you would like to change. +1. While viewing a published article in [Windows hardware developer documentation](https://learn.microsoft.com/windows-hardware/drivers/), click the **Edit** button in the upper right of the page. You will be redirected to the corresponding Markdown source file in the [GitHub repository](https://github.com/MicrosoftDocs/windows-driver-docs). If you're already in the [GitHub repo](https://github.com/MicrosoftDocs/windows-driver-docs), you can just navigate to the source file you would like to change. 2. If you don't already have a GitHub account, click **Sign Up** in the upper right and create a new account. 3. From the GitHub page you would like to change, click the pencil icon. 4. Modify the file and use the preview tab to ensure the changes look good. @@ -24,15 +24,11 @@ If you'd like to suggest a change to the docs, follow these steps: After you create the pull request, a member of the Windows Driver Documentation team will review your changes. -If your request is accepted, updates are published to [Windows hardware developer documentation](https://docs.microsoft.com/windows-hardware/drivers). - -If you're a Microsoft employee and you need to collaborate in a private environment, please contact the `windowsdriverdev` alias. +If your request is accepted, updates are published to [Windows hardware developer documentation](https://learn.microsoft.com/windows-hardware/drivers). ## Making more substantial changes -To make substantial changes to an existing article, add or change images, or contribute a new article, we recommend forking the official repo into your GitHub account, and then creating a local clone. - -For more info, see [Fork a Repo](https://help.github.com/articles/fork-a-repo/). +To make substantial changes to an existing article, add or change images, or contribute a new article, we recommend forking the official repo into your GitHub account, and then creating a local clone. For more info, see [Fork a Repo](https://help.github.com/articles/fork-a-repo/). ## Using issues to provide feedback on Windows driver documentation diff --git a/README.md b/README.md index e043bb499b..90219cc543 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ For more information see the [Code of Conduct FAQ](https://opensource.microsoft. # Windows Driver Documentation -Welcome to the Windows driver docs repository, housing the source for the official [Windows hardware developer documentation](https://docs.microsoft.com/windows-hardware/drivers). +Welcome to the Windows driver docs repository, housing the source for the official [Windows hardware developer documentation](https://learn.microsoft.com/windows-hardware/drivers). If you're looking for the driver reference (API/DDI) documentation, it's in the [`windows-driver-docs-ddi` GitHub repository](https://github.com/MicrosoftDocs/windows-driver-docs-ddi). diff --git a/windows-driver-docs-pr/3dprint/3d-manufacturing-keywords-overview.md b/windows-driver-docs-pr/3dprint/3d-manufacturing-keywords-overview.md index 1192d21745..10bf295fa8 100644 --- a/windows-driver-docs-pr/3dprint/3d-manufacturing-keywords-overview.md +++ b/windows-driver-docs-pr/3dprint/3d-manufacturing-keywords-overview.md @@ -1,7 +1,7 @@ --- title: 3D manufacturing keywords overview description: The Print Schema 3D manufacturing keywords identify possible settings for a device's capabilities or selected settings for a device configuration. -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # 3D manufacturing keywords overview diff --git a/windows-driver-docs-pr/3dprint/3d-partner-onboarding-guide.md b/windows-driver-docs-pr/3dprint/3d-partner-onboarding-guide.md index 491e282bc3..1ddd1c0c62 100644 --- a/windows-driver-docs-pr/3dprint/3d-partner-onboarding-guide.md +++ b/windows-driver-docs-pr/3dprint/3d-partner-onboarding-guide.md @@ -1,7 +1,7 @@ --- title: 3D print partner onboarding guide -description: This topic describes how to implement 3D printer drivers that are then published on Windows Update. -ms.date: 08/13/2021 +description: This article describes how to implement 3D printer drivers that are then published on Windows Update. +ms.date: 03/17/2023 --- # 3D print partner onboarding guide @@ -16,16 +16,16 @@ A plug-and-play 3D printer on Windows 10 is implemented through a pair of driver - Implements the slicer. The driver takes [3MF](https://3mf.io/) as input and produces G-Code or other similar machine level data. -- Creates the print queue. The device appears under **Devices and Printers** and in the **3D Print Dialog** for compatible [3D Printing applications](https://developer.microsoft.com/windows/hardware/3d-print/software-partners). +- Creates the print queue. The device appears under **Devices and Printers** and in the **3D Print Dialog** for compatible 3D printing applications. ### Lower driver (USB driver) - Implements wire protocol (typically USB Serial or native USB) - Kernel mode driver creates the ENUM\\3DPRINTER device node for the upper driver - - User mode component (Partner DLL) sends the G-Code to the device + - Reports device capabilities, job status and implements job cancel - Installs 3D print service and the 3D port monitor (3dmon) @@ -44,21 +44,18 @@ A plug-and-play 3D printer on Windows 10 is implemented through a pair of driver - Download and install [Visual Studio Community Edition](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=community) - - Download and install the [Windows 10 SDK](https://developer.microsoft.com/windows/downloads/windows-10-sdk/) + - Download and install the [Windows SDK](https://developer.microsoft.com/windows/downloads/windows-sdk/) - Download and install the [3D printing SDK](https://download.microsoft.com/download/6/2/7/62727B7E-D493-4B7E-9429-56FF84365852/MS3DPrinting.msi) - > [!NOTE] - > The 3D printing SDK will be installed in C:\\Program Files (x86)\\Microsoft SDKs\\3D Printing. + The 3D printing SDK will be installed in C:\\Program Files (x86)\\Microsoft SDKs\\3D Printing. 1. Implement the USB driver - A manufacturer can use the Microsoft USB driver for their 3D printer by creating a partner DLL. For more information, see [3D printer custom USB interface support](3d-printer-custom-usb-interface.md). - - If the printer is using the Microsoft Slicer, the Hardware ID that it creates must be **Enum\\3DPrint\\MS3DPrint** - > [!NOTE] - > If the printer is using a custom slicer, continue with steps 4-7. + If the printer is using a custom slicer, continue with steps 4-7. 1. Build the Fabrikam driver (slicer template only) @@ -80,11 +77,8 @@ A plug-and-play 3D printer on Windows 10 is implemented through a pair of driver ```inf %DeviceName%=FabrikamPrintDriverV4\_Install,3DPRINTER\\Fabrikam1 - %DeviceNamePlus%=FabrikamPrintDriverV4\_Install,3DPRINTER\\Fabrikam2 - DeviceName="CONTOSO FABRIKAM 1" - DeviceNamePlus="CONTOSO FABRIKAM 2" ``` diff --git a/windows-driver-docs-pr/3dprint/3d-printer-custom-usb-interface.md b/windows-driver-docs-pr/3dprint/3d-printer-custom-usb-interface.md index 13e4f314ad..60c3547525 100644 --- a/windows-driver-docs-pr/3dprint/3d-printer-custom-usb-interface.md +++ b/windows-driver-docs-pr/3dprint/3d-printer-custom-usb-interface.md @@ -1,7 +1,7 @@ --- title: Custom USB interface support for 3D printers description: This topic describes how to enable a custom USB interfaces for 3D printers in the v3 and v4 print driver ecosystems. -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Enable a custom USB interface for a 3D printer diff --git a/windows-driver-docs-pr/3dprint/3d-printing-partners.md b/windows-driver-docs-pr/3dprint/3d-printing-partners.md index 054f73783b..9096dfc994 100644 --- a/windows-driver-docs-pr/3dprint/3d-printing-partners.md +++ b/windows-driver-docs-pr/3dprint/3d-printing-partners.md @@ -1,7 +1,7 @@ --- title: 3D hardware partners description: Microsoft has teamed up with 3D hardware partners to make end-to-end 3D manufacturing accessible to anyone using Windows 10. -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # 3D hardware partners diff --git a/windows-driver-docs-pr/3dprint/3d-printing-sample-wsd-app.md b/windows-driver-docs-pr/3dprint/3d-printing-sample-wsd-app.md index 10695f6591..559d02dbde 100644 --- a/windows-driver-docs-pr/3dprint/3d-printing-sample-wsd-app.md +++ b/windows-driver-docs-pr/3dprint/3d-printing-sample-wsd-app.md @@ -1,7 +1,7 @@ --- title: 3D printing sample WSD app description: This section contains detailed instructions for building and deploying the web service device (WSD) sample application with the included 3D print driver. -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # 3D printing sample WSD app diff --git a/windows-driver-docs-pr/3dprint/configuring-the-device.md b/windows-driver-docs-pr/3dprint/configuring-the-device.md index 3daa9bb805..d2fdd3bfb6 100644 --- a/windows-driver-docs-pr/3dprint/configuring-the-device.md +++ b/windows-driver-docs-pr/3dprint/configuring-the-device.md @@ -1,7 +1,7 @@ --- title: Configuring the device description: To configure the device, you should have a 3D printer device in the Devices and Printers Control Panel and can print to G-Code using the Microsoft Slicer. -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Configuring the device diff --git a/windows-driver-docs-pr/3dprint/device-control-keywords.md b/windows-driver-docs-pr/3dprint/device-control-keywords.md index 51feccaaaf..d4ff305696 100644 --- a/windows-driver-docs-pr/3dprint/device-control-keywords.md +++ b/windows-driver-docs-pr/3dprint/device-control-keywords.md @@ -1,7 +1,7 @@ --- title: Device control keywords description: These keywords are used to provide control over the 3D manufacturing device. -ms.date: 08/23/2021 +ms.date: 03/17/2023 --- # Device control keywords diff --git a/windows-driver-docs-pr/3dprint/driver-installation.md b/windows-driver-docs-pr/3dprint/driver-installation.md index 04cd4f6201..05abcd7aec 100644 --- a/windows-driver-docs-pr/3dprint/driver-installation.md +++ b/windows-driver-docs-pr/3dprint/driver-installation.md @@ -1,7 +1,7 @@ --- title: Driver installation description: The print driver provided in this SDK is an experimental 3D printer device driver still under development. -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Driver installation diff --git a/windows-driver-docs-pr/3dprint/enabling-wsprint-on-a-device.md b/windows-driver-docs-pr/3dprint/enabling-wsprint-on-a-device.md index a0f13687a3..bc67cdeecb 100644 --- a/windows-driver-docs-pr/3dprint/enabling-wsprint-on-a-device.md +++ b/windows-driver-docs-pr/3dprint/enabling-wsprint-on-a-device.md @@ -1,7 +1,7 @@ --- title: Enable WSPrint 2.0 on a device description: Use these settings to enable WSPrint 2.0 on a device -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Enable WSPrint 2.0 on a device diff --git a/windows-driver-docs-pr/3dprint/example-printcapabilities-document.md b/windows-driver-docs-pr/3dprint/example-printcapabilities-document.md index 9b0f155dad..75bcd869e4 100644 --- a/windows-driver-docs-pr/3dprint/example-printcapabilities-document.md +++ b/windows-driver-docs-pr/3dprint/example-printcapabilities-document.md @@ -1,7 +1,7 @@ --- title: PrintCapabilities document example description: The keywords used in the following example are for illustration only, although they generally conform to the Print Schema keywords for 3D manufacturing. -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # PrintCapabilities document example diff --git a/windows-driver-docs-pr/3dprint/example-printticket-document.md b/windows-driver-docs-pr/3dprint/example-printticket-document.md index 8e8a9b3fa2..ccc6de60aa 100644 --- a/windows-driver-docs-pr/3dprint/example-printticket-document.md +++ b/windows-driver-docs-pr/3dprint/example-printticket-document.md @@ -1,7 +1,7 @@ --- title: PrintTicket document example description: The keywords in this example are for illustration only, although they reflect the Print Schema keywords for 3D manufacturing. -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # PrintTicket document example diff --git a/windows-driver-docs-pr/3dprint/index.md b/windows-driver-docs-pr/3dprint/index.md index b30f9ff4d6..730ce99c46 100644 --- a/windows-driver-docs-pr/3dprint/index.md +++ b/windows-driver-docs-pr/3dprint/index.md @@ -1,8 +1,7 @@ --- title: 3D printer driver design guide description: This section provides information about 3D printer drivers in Windows 10. -ms.date: 08/13/2021 -ms.topic: article +ms.date: 03/17/2023 --- # 3D printer driver design guide diff --git a/windows-driver-docs-pr/3dprint/install-the-driver-and-sample-app.md b/windows-driver-docs-pr/3dprint/install-the-driver-and-sample-app.md index e15156802f..8f2d86c289 100644 --- a/windows-driver-docs-pr/3dprint/install-the-driver-and-sample-app.md +++ b/windows-driver-docs-pr/3dprint/install-the-driver-and-sample-app.md @@ -1,7 +1,7 @@ --- title: Install the driver and sample app description: This section provides information on installing the driver and the WSD sample app. -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Install the driver and sample app diff --git a/windows-driver-docs-pr/3dprint/material-keywords.md b/windows-driver-docs-pr/3dprint/material-keywords.md index 5fc563e2fa..958e96f555 100644 --- a/windows-driver-docs-pr/3dprint/material-keywords.md +++ b/windows-driver-docs-pr/3dprint/material-keywords.md @@ -1,7 +1,7 @@ --- title: Material keywords description: These keywords describe the raw material in the device used to create 3D objects. -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Material keywords diff --git a/windows-driver-docs-pr/3dprint/microsoft-standard-driver-for-3d-printers-.md b/windows-driver-docs-pr/3dprint/microsoft-standard-driver-for-3d-printers-.md index 79fbfc1a4a..9108c3b689 100644 --- a/windows-driver-docs-pr/3dprint/microsoft-standard-driver-for-3d-printers-.md +++ b/windows-driver-docs-pr/3dprint/microsoft-standard-driver-for-3d-printers-.md @@ -1,7 +1,7 @@ --- title: Getting started guide - Microsoft Standard Driver for 3D Printers description: The Microsoft Standard Driver for 3D Printers allows developers to easily make their printer compatible with Windows 10. -ms.date: 08/13/2021 +ms.date: 03/17/2023 --- # Getting started guide - Microsoft Standard Driver for 3D Printers diff --git a/windows-driver-docs-pr/3dprint/ms3dprint-standard-g-code-driver.md b/windows-driver-docs-pr/3dprint/ms3dprint-standard-g-code-driver.md index 7bf0db8ffd..e1b1b9a405 100644 --- a/windows-driver-docs-pr/3dprint/ms3dprint-standard-g-code-driver.md +++ b/windows-driver-docs-pr/3dprint/ms3dprint-standard-g-code-driver.md @@ -1,7 +1,7 @@ --- title: MS3DPrint Standard G-Code driver description: The MS3DPrint Standard G-Code driver implements a typical Windows 8.1 or Windows 10 driver for fused filament fabrication 3D printers that run with G-Code, particularly open source printers, including those from the RepRap project. -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # MS3DPrint Standard G-Code driver diff --git a/windows-driver-docs-pr/3dprint/output-keywords.md b/windows-driver-docs-pr/3dprint/output-keywords.md index 57ed8bfc94..c0069db665 100644 --- a/windows-driver-docs-pr/3dprint/output-keywords.md +++ b/windows-driver-docs-pr/3dprint/output-keywords.md @@ -1,7 +1,7 @@ --- title: Output keywords description: These keywords are used to describe the actual output processes for a given 3D manufacturing job. -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Output keywords diff --git a/windows-driver-docs-pr/3dprint/print-files-to-the-wsd-sample.md b/windows-driver-docs-pr/3dprint/print-files-to-the-wsd-sample.md index d74ec70a61..65cbebb4ad 100644 --- a/windows-driver-docs-pr/3dprint/print-files-to-the-wsd-sample.md +++ b/windows-driver-docs-pr/3dprint/print-files-to-the-wsd-sample.md @@ -1,7 +1,7 @@ --- title: Print files to the WSD sample description: This section describes how to print to the WSD sample. -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Print files to the WSD sample diff --git a/windows-driver-docs-pr/3dprint/print-schema-glossary.md b/windows-driver-docs-pr/3dprint/print-schema-glossary.md index fc753c56b5..6dffd0df89 100644 --- a/windows-driver-docs-pr/3dprint/print-schema-glossary.md +++ b/windows-driver-docs-pr/3dprint/print-schema-glossary.md @@ -2,7 +2,7 @@ title: Print schema glossary description: A glossary of terms regarding the 3D print schema. The glossary includes explanations for terms such as assembly, nozzle, raft. Robots: noindex, nofollow -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Print schema glossary diff --git a/windows-driver-docs-pr/3dprint/print-schema-keywords-for-3d-manufacturing.md b/windows-driver-docs-pr/3dprint/print-schema-keywords-for-3d-manufacturing.md index 571e56d49c..11e6f79a7b 100644 --- a/windows-driver-docs-pr/3dprint/print-schema-keywords-for-3d-manufacturing.md +++ b/windows-driver-docs-pr/3dprint/print-schema-keywords-for-3d-manufacturing.md @@ -1,7 +1,7 @@ --- title: Print Schema keywords for 3D manufacturing description: The Print Schema keywords for 3D manufacturing is a supplemental specification to the Print Schema Specification. -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Print Schema keywords for 3D manufacturing diff --git a/windows-driver-docs-pr/3dprint/print-schema-references.md b/windows-driver-docs-pr/3dprint/print-schema-references.md index edef6b7246..f3d24e9f54 100644 --- a/windows-driver-docs-pr/3dprint/print-schema-references.md +++ b/windows-driver-docs-pr/3dprint/print-schema-references.md @@ -1,7 +1,7 @@ --- title: Print schema references description: Provides references and links to industry standards, specifications, and technical articles. -ms.date: 12/13/2021 +ms.date: 03/17/2023 --- # Print schema references diff --git a/windows-driver-docs-pr/3dprint/sample-configuration-xml.md b/windows-driver-docs-pr/3dprint/sample-configuration-xml.md index 14f456e323..2fd4006a40 100644 --- a/windows-driver-docs-pr/3dprint/sample-configuration-xml.md +++ b/windows-driver-docs-pr/3dprint/sample-configuration-xml.md @@ -1,7 +1,7 @@ --- title: Sample configuration XML description: Use the sample configuration XML in this topic to develop configuration files for your device. -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Sample configuration XML diff --git a/windows-driver-docs-pr/3dprint/slicer-settings.md b/windows-driver-docs-pr/3dprint/slicer-settings.md index 0b3baf94c1..6d28e483d4 100644 --- a/windows-driver-docs-pr/3dprint/slicer-settings.md +++ b/windows-driver-docs-pr/3dprint/slicer-settings.md @@ -1,7 +1,7 @@ --- title: Slicer settings description: The configuration file XML contains a number of settings that need to be adjusted for a specific 3D Printer device to control the print capabilities exposed to the 3D Print Dialog in Windows. -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Slicer settings @@ -549,7 +549,7 @@ The configuration file XML contains a number of settings that need to be adjuste ## Slicer settings (name) | Setting name | Description | -|--|--| +|---|---| | \$extrudertemperature\$, \$extruder2temperature\$ | The temperature of the first and respectively the second extruder, as specified by <psk3dx:extrudertemperature> in the Materials section in the XML. These variables are being deprecated and being replaced by \$MaterialSetup\$. | | \$platformtemperature\$ | The temperature of the heated bed as specified by the <psk3dx:platformtemperature> entry in the last material in the list. | | \$MaterialSetup*x*\$ | Where *x* is a single digit. The material setup section <psk3dx:SetupCommands> in materials. For example, \$MaterialSetup3\$ represents the 3rd material in the list, typically the 3rd extruder. | diff --git a/windows-driver-docs-pr/3dprint/test-sign-a-driver-package.md b/windows-driver-docs-pr/3dprint/test-sign-a-driver-package.md index cf0bb0cdfe..202dc1a8e9 100644 --- a/windows-driver-docs-pr/3dprint/test-sign-a-driver-package.md +++ b/windows-driver-docs-pr/3dprint/test-sign-a-driver-package.md @@ -1,7 +1,7 @@ --- title: Test-sign a driver package description: This section describes how to test-sign a driver package. -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Test-sign a driver package diff --git a/windows-driver-docs-pr/acpi/accessing-an-operation-region.md b/windows-driver-docs-pr/acpi/accessing-an-operation-region.md index d9242a0bdf..3fed6e57e5 100644 --- a/windows-driver-docs-pr/acpi/accessing-an-operation-region.md +++ b/windows-driver-docs-pr/acpi/accessing-an-operation-region.md @@ -6,7 +6,7 @@ keywords: - operation regions WDK ACPI - function drivers WDK ACPI , operation regions - WDM function drivers WDK ACPI , operation regions -ms.date: 04/14/2021 +ms.date: 03/17/2023 --- # Accessing an Operation Region diff --git a/windows-driver-docs-pr/acpi/acpi-enum-child-length-from-child.md b/windows-driver-docs-pr/acpi/acpi-enum-child-length-from-child.md index 3aee674768..6c9fac5b11 100644 --- a/windows-driver-docs-pr/acpi/acpi-enum-child-length-from-child.md +++ b/windows-driver-docs-pr/acpi/acpi-enum-child-length-from-child.md @@ -3,7 +3,8 @@ title: ACPI_ENUM_CHILD_LENGTH_FROM_CHILD macro description: The ACPI_ENUM_CHILD_LENGTH_FROM_CHILD macro calculates the size, in bytes, of a variable-length ACPI_ENUM_CHILD structure. keywords: - ACPI_ENUM_CHILD_LENGTH_FROM_CHILD macro ACPI Devices -ms.date: 08/17/2021 +ms.date: 03/17/2023 +ms.topic: reference --- # ACPI_ENUM_CHILD_LENGTH_FROM_CHILD macro diff --git a/windows-driver-docs-pr/acpi/acpi-enum-child-next.md b/windows-driver-docs-pr/acpi/acpi-enum-child-next.md index d74e9ed09d..f8fccb75c2 100644 --- a/windows-driver-docs-pr/acpi/acpi-enum-child-next.md +++ b/windows-driver-docs-pr/acpi/acpi-enum-child-next.md @@ -3,7 +3,8 @@ title: ACPI_ENUM_CHILD_NEXT macro description: The ACPI_ENUM_CHILD_NEXT macro calculates a pointer to the next ACPI_ENUM_CHILD structure in an array of variable length ACPI_ENUM_CHILD structures. keywords: - ACPI_ENUM_CHILD_NEXT macro ACPI Devices -ms.date: 08/17/2021 +ms.date: 03/17/2023 +ms.topic: reference --- # ACPI_ENUM_CHILD_NEXT macro diff --git a/windows-driver-docs-pr/acpi/acpi-manipulate-lock-buffer.md b/windows-driver-docs-pr/acpi/acpi-manipulate-lock-buffer.md index 8eb11b88e0..e495369137 100644 --- a/windows-driver-docs-pr/acpi/acpi-manipulate-lock-buffer.md +++ b/windows-driver-docs-pr/acpi/acpi-manipulate-lock-buffer.md @@ -3,7 +3,8 @@ title: ACPI_MANIPULATE_LOCK_BUFFER structure description: The ACPI_MANIPULATE_LOCK_BUFFER macro is reserved for internal use only with an IOCTL_ACPI_ACQUIRE_GLOBAL_LOCK and IOCTL_ACPI_RELEASE_GLOBAL_LOCK. keywords: - ACPI_MANIPULATE_LOCK_BUFFER structure ACPI Devices -ms.date: 08/17/2021 +ms.date: 03/17/2023 +ms.topic: reference --- # ACPI_MANIPULATE_LOCK_BUFFER structure diff --git a/windows-driver-docs-pr/acpi/acpi-method-argument-length-from-argument.md b/windows-driver-docs-pr/acpi/acpi-method-argument-length-from-argument.md index bd372364c8..3cd6905393 100644 --- a/windows-driver-docs-pr/acpi/acpi-method-argument-length-from-argument.md +++ b/windows-driver-docs-pr/acpi/acpi-method-argument-length-from-argument.md @@ -3,7 +3,8 @@ title: ACPI_METHOD_ARGUMENT_LENGTH_FROM_ARGUMENT macro description: The ACPI_METHOD_ARGUMENT_LENGTH_FROM_ARGUMENT macro calculates the size, in bytes, of the data that is contained in the Data array of an ACPI_METHOD_ARGUMENT structure. keywords: - ACPI_METHOD_ARGUMENT_LENGTH_FROM_ARGUMENT macro ACPI Devices -ms.date: 08/17/2021 +ms.date: 03/17/2023 +ms.topic: reference --- # ACPI_METHOD_ARGUMENT_LENGTH_FROM_ARGUMENT macro diff --git a/windows-driver-docs-pr/acpi/acpi-method-argument-length.md b/windows-driver-docs-pr/acpi/acpi-method-argument-length.md index cce734b856..df1424109c 100644 --- a/windows-driver-docs-pr/acpi/acpi-method-argument-length.md +++ b/windows-driver-docs-pr/acpi/acpi-method-argument-length.md @@ -3,7 +3,8 @@ title: ACPI_METHOD_ARGUMENT_LENGTH macro description: The ACPI_METHOD_ARGUMENT_LENGTH macro calculates the size, in bytes, of a variable-length ACPI_METHOD_ARGUMENT structure that contains data of a specified size, in bytes. keywords: - ACPI_METHOD_ARGUMENT_LENGTH macro ACPI Devices -ms.date: 08/17/2021 +ms.date: 03/17/2023 +ms.topic: reference --- # ACPI_METHOD_ARGUMENT_LENGTH macro diff --git a/windows-driver-docs-pr/acpi/acpi-method-next-argument.md b/windows-driver-docs-pr/acpi/acpi-method-next-argument.md index 88a64a03d2..78c716fe15 100644 --- a/windows-driver-docs-pr/acpi/acpi-method-next-argument.md +++ b/windows-driver-docs-pr/acpi/acpi-method-next-argument.md @@ -3,7 +3,8 @@ title: ACPI_METHOD_NEXT_ARGUMENT macro description: The ACPI_METHOD_NEXT_ARGUMENT structure returns a pointer to the next ACPI_METHOD_ARGUMENT structure in an array of ACPI_METHOD_ARGUMENT structures. keywords: - ACPI_METHOD_NEXT_ARGUMENT macro ACPI Devices -ms.date: 08/17/2021 +ms.date: 03/17/2023 +ms.topic: reference --- # ACPI_METHOD_NEXT_ARGUMENT macro diff --git a/windows-driver-docs-pr/acpi/acpi-method-set-argument-buffer.md b/windows-driver-docs-pr/acpi/acpi-method-set-argument-buffer.md index c91e387e0e..87727aeb02 100644 --- a/windows-driver-docs-pr/acpi/acpi-method-set-argument-buffer.md +++ b/windows-driver-docs-pr/acpi/acpi-method-set-argument-buffer.md @@ -3,7 +3,8 @@ title: ACPI_METHOD_SET_ARGUMENT_BUFFER macro description: The ACPI_METHOD_SET_ARGUMENT_BUFFER macro sets the members of an ACPI_METHOD_ARGUMENT structure for custom data that is supplied in a data buffer. keywords: - ACPI_METHOD_SET_ARGUMENT_BUFFER macro ACPI Devices -ms.date: 08/17/2021 +ms.date: 03/17/2023 +ms.topic: reference --- # ACPI_METHOD_SET_ARGUMENT_BUFFER macro diff --git a/windows-driver-docs-pr/acpi/acpi-method-set-argument-integer.md b/windows-driver-docs-pr/acpi/acpi-method-set-argument-integer.md index be921700e8..bb5a777943 100644 --- a/windows-driver-docs-pr/acpi/acpi-method-set-argument-integer.md +++ b/windows-driver-docs-pr/acpi/acpi-method-set-argument-integer.md @@ -3,7 +3,8 @@ title: ACPI_METHOD_SET_ARGUMENT_INTEGER macro description: The ACPI_METHOD_SET_ARGUMENT_INTEGER macro sets the members of an ACPI_METHOD_ARGUMENT structure for a single integer value. keywords: - ACPI_METHOD_SET_ARGUMENT_INTEGER macro ACPI Devices -ms.date: 08/17/2021 +ms.date: 03/17/2023 +ms.topic: reference --- # ACPI_METHOD_SET_ARGUMENT_INTEGER macro diff --git a/windows-driver-docs-pr/acpi/acpi-method-set-argument-string.md b/windows-driver-docs-pr/acpi/acpi-method-set-argument-string.md index 367b67fb49..6355a9fbc1 100644 --- a/windows-driver-docs-pr/acpi/acpi-method-set-argument-string.md +++ b/windows-driver-docs-pr/acpi/acpi-method-set-argument-string.md @@ -3,7 +3,8 @@ title: ACPI_METHOD_SET_ARGUMENT_STRING macro description: The ACPI_METHOD_SET_ARGUMENT_STRING macro sets the members of an ACPI_METHOD_ARGUMENT structure for a string value. keywords: - ACPI_METHOD_SET_ARGUMENT_STRING macro ACPI Devices -ms.date: 08/17/2021 +ms.date: 03/17/2023 +ms.topic: reference --- # ACPI_METHOD_SET_ARGUMENT_STRING macro diff --git a/windows-driver-docs-pr/acpi/control-method-input-buffer-structures.md b/windows-driver-docs-pr/acpi/control-method-input-buffer-structures.md index 54cb61b8bf..7aa5fb0807 100644 --- a/windows-driver-docs-pr/acpi/control-method-input-buffer-structures.md +++ b/windows-driver-docs-pr/acpi/control-method-input-buffer-structures.md @@ -1,7 +1,7 @@ --- title: Control Method Input Buffer Structures description: Provides information about control method input buffer structures -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Control Method Input Buffer Structures diff --git a/windows-driver-docs-pr/acpi/control-method-macros.md b/windows-driver-docs-pr/acpi/control-method-macros.md index 9ac476a745..17bce13244 100644 --- a/windows-driver-docs-pr/acpi/control-method-macros.md +++ b/windows-driver-docs-pr/acpi/control-method-macros.md @@ -3,7 +3,7 @@ title: Control Method Macros description: Provides information about control method macros keywords: - ACPI control methods WDK, macros -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Control Method Macros diff --git a/windows-driver-docs-pr/acpi/device-stacks-for-an-acpi-device.md b/windows-driver-docs-pr/acpi/device-stacks-for-an-acpi-device.md index 4a4d7b3dcd..241974dcad 100644 --- a/windows-driver-docs-pr/acpi/device-stacks-for-an-acpi-device.md +++ b/windows-driver-docs-pr/acpi/device-stacks-for-an-acpi-device.md @@ -10,7 +10,7 @@ keywords: - root bus drivers WDK ACPI - function drivers WDK ACPI , device stacks - WDM function drivers WDK ACPI , device stacks -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Device Stacks for an ACPI Device diff --git a/windows-driver-docs-pr/acpi/enumerating-child-devices-and-control-methods.md b/windows-driver-docs-pr/acpi/enumerating-child-devices-and-control-methods.md index 33594c0f39..84fd992a73 100644 --- a/windows-driver-docs-pr/acpi/enumerating-child-devices-and-control-methods.md +++ b/windows-driver-docs-pr/acpi/enumerating-child-devices-and-control-methods.md @@ -6,7 +6,7 @@ keywords: - ACPI devices WDK , enumerating control methods - ACPI namespaces WDK - ACPI control methods WDK , enumerating -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Enumerating Child Devices and Control Methods diff --git a/windows-driver-docs-pr/acpi/evaluating-a-control-method-that-takes-input-arguments.md b/windows-driver-docs-pr/acpi/evaluating-a-control-method-that-takes-input-arguments.md index 69ccd9af1e..d91630fe8b 100644 --- a/windows-driver-docs-pr/acpi/evaluating-a-control-method-that-takes-input-arguments.md +++ b/windows-driver-docs-pr/acpi/evaluating-a-control-method-that-takes-input-arguments.md @@ -1,7 +1,7 @@ --- title: Evaluating a Control Method That Takes Input Arguments description: Provides information about evaluating a control method that takes input arguments -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Evaluating a Control Method That Takes Input Arguments diff --git a/windows-driver-docs-pr/acpi/evaluating-a-control-method-without-input-arguments.md b/windows-driver-docs-pr/acpi/evaluating-a-control-method-without-input-arguments.md index 308b94e08b..a6aace6965 100644 --- a/windows-driver-docs-pr/acpi/evaluating-a-control-method-without-input-arguments.md +++ b/windows-driver-docs-pr/acpi/evaluating-a-control-method-without-input-arguments.md @@ -1,7 +1,7 @@ --- title: Evaluating a Control Method Without Input Arguments description: Provides information about evaluating a control method without input arguments -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Evaluating a Control Method Without Input Arguments diff --git a/windows-driver-docs-pr/acpi/evaluating-acpi-control-methods-synchronously.md b/windows-driver-docs-pr/acpi/evaluating-acpi-control-methods-synchronously.md index 9388051855..5172af494b 100644 --- a/windows-driver-docs-pr/acpi/evaluating-acpi-control-methods-synchronously.md +++ b/windows-driver-docs-pr/acpi/evaluating-acpi-control-methods-synchronously.md @@ -5,7 +5,7 @@ keywords: - ACPI control methods WDK , evaluating synchronously - ACPI control methods WDK , input buffer structures - ACPI control methods WDK , SendDownStreamIrp code sample -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Evaluating ACPI Control Methods Synchronously diff --git a/windows-driver-docs-pr/acpi/evaluating-acpi-control-methods.md b/windows-driver-docs-pr/acpi/evaluating-acpi-control-methods.md index f09ef154c5..ead5b72250 100644 --- a/windows-driver-docs-pr/acpi/evaluating-acpi-control-methods.md +++ b/windows-driver-docs-pr/acpi/evaluating-acpi-control-methods.md @@ -4,7 +4,7 @@ description: Provides information about evaluating ACPI control methods keywords: - ACPI control methods WDK , evaluating - ACPI devices WDK , evaluating control methods -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Evaluating ACPI Control Methods diff --git a/windows-driver-docs-pr/acpi/implementing-an-operation-region-handler.md b/windows-driver-docs-pr/acpi/implementing-an-operation-region-handler.md index 621cac4e8c..c0e905c1d1 100644 --- a/windows-driver-docs-pr/acpi/implementing-an-operation-region-handler.md +++ b/windows-driver-docs-pr/acpi/implementing-an-operation-region-handler.md @@ -6,7 +6,7 @@ keywords: - operation regions WDK ACPI - function drivers WDK ACPI , operation regions - WDM function drivers WDK ACPI , operation regions -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Implementing an Operation Region Handler diff --git a/windows-driver-docs-pr/acpi/index.md b/windows-driver-docs-pr/acpi/index.md index bf4a6d5bc6..cd26161ac4 100644 --- a/windows-driver-docs-pr/acpi/index.md +++ b/windows-driver-docs-pr/acpi/index.md @@ -1,8 +1,7 @@ --- title: ACPI design guide description: This section describes how device drivers can interface an Advanced Configuration and Power Interface (ACPI) device. ACPI devices are defined by the Advanced Configuration and Power Interface (ACPI) Specification. -ms.date: 08/13/2021 -ms.topic: article +ms.date: 03/17/2023 --- # ACPI design guide @@ -14,7 +13,7 @@ ACPI devices are defined by the [Advanced Configuration and Power Interface (ACP ## In this section | Section | Description | -|--|--| +|---|---| | [Supporting ACPI Devices](supporting-acpi-devices.md) | Provides information about how to use a Windows Driver Model (WDM) function driver to enhance the functionality of an ACPI device. | | [Evaluating ACPI Control Methods](evaluating-acpi-control-methods.md) | Provides information about how device drivers that comply with the requirements of [Kernel-Mode Driver Framework (KMDF)](../kernel/index.md), [User-Mode Driver Framework (UMDF)](../wdf/getting-started-with-umdf-version-2.md), or [Windows Driver Model (WDM)](../kernel/introduction-to-wdm.md) can evaluate ACPI control methods. | | [How to Identify the Windows Version in ACPI by Using _OSI](winacpi-osi.md) | Provides information about the ACPI Source Language (ASL) Operating System Interface Level (\_OSI) method used to identify the host operating system. | diff --git a/windows-driver-docs-pr/acpi/maintaining-an-operation-region-memory-buffer.md b/windows-driver-docs-pr/acpi/maintaining-an-operation-region-memory-buffer.md index d43e6b28ac..9a0aaa9a8c 100644 --- a/windows-driver-docs-pr/acpi/maintaining-an-operation-region-memory-buffer.md +++ b/windows-driver-docs-pr/acpi/maintaining-an-operation-region-memory-buffer.md @@ -8,7 +8,7 @@ keywords: - WDM function drivers WDK ACPI , operation regions - operation region memory buffer WDK ACPI - memory buffers WDK ACPI -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Maintaining an Operation Region Memory Buffer diff --git a/windows-driver-docs-pr/acpi/operation-of-an-acpi-device-function-driver.md b/windows-driver-docs-pr/acpi/operation-of-an-acpi-device-function-driver.md index 28bf9ed3b4..fe72d7ec91 100644 --- a/windows-driver-docs-pr/acpi/operation-of-an-acpi-device-function-driver.md +++ b/windows-driver-docs-pr/acpi/operation-of-an-acpi-device-function-driver.md @@ -6,7 +6,7 @@ keywords: - vendor-supplied function drivers WDK ACPI - function drivers WDK ACPI , operation - WDM function drivers WDK ACPI , operation -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Operation of an ACPI Device Function Driver diff --git a/windows-driver-docs-pr/acpi/providing-a-vendor-defined-acpi-device-interface.md b/windows-driver-docs-pr/acpi/providing-a-vendor-defined-acpi-device-interface.md index c6518a57a2..17c2dff474 100644 --- a/windows-driver-docs-pr/acpi/providing-a-vendor-defined-acpi-device-interface.md +++ b/windows-driver-docs-pr/acpi/providing-a-vendor-defined-acpi-device-interface.md @@ -7,7 +7,7 @@ keywords: - device interfaces WDK ACPI - function drivers WDK ACPI , vendor-defined device interfaces - WDM function drivers WDK ACPI , vendor-defined device interfaces -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Providing a Vendor-Defined ACPI Device Interface diff --git a/windows-driver-docs-pr/acpi/registering-and-deregistering-an-operation-region-handler.md b/windows-driver-docs-pr/acpi/registering-and-deregistering-an-operation-region-handler.md index 607921892f..756df557c4 100644 --- a/windows-driver-docs-pr/acpi/registering-and-deregistering-an-operation-region-handler.md +++ b/windows-driver-docs-pr/acpi/registering-and-deregistering-an-operation-region-handler.md @@ -8,7 +8,7 @@ keywords: - WDM function drivers WDK ACPI , operation regions - registering operation region handlers - deregistering operation region handlers -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Registering and Deregistering an Operation Region Handler diff --git a/windows-driver-docs-pr/acpi/senddownstreamirp-function.md b/windows-driver-docs-pr/acpi/senddownstreamirp-function.md index f84f13dee7..63bf039a74 100644 --- a/windows-driver-docs-pr/acpi/senddownstreamirp-function.md +++ b/windows-driver-docs-pr/acpi/senddownstreamirp-function.md @@ -1,7 +1,7 @@ --- title: SendDownStreamIrp Function description: Provides information about the SendDownStreamIrp function -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # SendDownStreamIrp Function diff --git a/windows-driver-docs-pr/acpi/sending-an-ioctl-acpi-enum-children-request.md b/windows-driver-docs-pr/acpi/sending-an-ioctl-acpi-enum-children-request.md index 4e854b2569..d37766f073 100644 --- a/windows-driver-docs-pr/acpi/sending-an-ioctl-acpi-enum-children-request.md +++ b/windows-driver-docs-pr/acpi/sending-an-ioctl-acpi-enum-children-request.md @@ -1,7 +1,7 @@ --- title: Sending an IOCTL_ACPI_ENUM_CHILDREN Request description: Provides information about sending an IOCTL_ACPI_ENUM_CHILDREN request -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Sending an IOCTL_ACPI_ENUM_CHILDREN Request diff --git a/windows-driver-docs-pr/acpi/supporting-acpi-devices.md b/windows-driver-docs-pr/acpi/supporting-acpi-devices.md index 9007ec1975..e67506d541 100644 --- a/windows-driver-docs-pr/acpi/supporting-acpi-devices.md +++ b/windows-driver-docs-pr/acpi/supporting-acpi-devices.md @@ -10,7 +10,7 @@ keywords: - operation region handlers WDK ACPI - function drivers WDK ACPI - WDM function drivers WDK ACPI -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Supporting ACPI Devices diff --git a/windows-driver-docs-pr/acpi/supporting-an-operation-region.md b/windows-driver-docs-pr/acpi/supporting-an-operation-region.md index e6c2f66c33..0f680a798f 100644 --- a/windows-driver-docs-pr/acpi/supporting-an-operation-region.md +++ b/windows-driver-docs-pr/acpi/supporting-an-operation-region.md @@ -6,7 +6,7 @@ keywords: - operation regions WDK ACPI - function drivers WDK ACPI , operation regions - WDM function drivers WDK ACPI , operation regions -ms.date: 08/17/2021 +ms.date: 03/17/2023 --- # Supporting an Operation Region diff --git a/windows-driver-docs-pr/acpi/winacpi-osi.md b/windows-driver-docs-pr/acpi/winacpi-osi.md index 184584b685..997f775b5b 100644 --- a/windows-driver-docs-pr/acpi/winacpi-osi.md +++ b/windows-driver-docs-pr/acpi/winacpi-osi.md @@ -1,7 +1,7 @@ --- title: How to identify the Windows version in ACPI by using _OSI description: Provides information about the ACPI Source Language (ASL) Operating System Interface Level (_OSI) method used to identify the host operating system. -ms.date: 05/13/2022 +ms.date: 03/17/2023 ms.custom: contperf-fy22q4 --- @@ -53,7 +53,7 @@ This information applies to the following operating systems: - Windows XP -## The _OSImMethod +## The _OSI Method All recent versions of the Windows operating system support components of the [Advanced Configuration and Power Interface (ACPI) Specification](https://uefi.org/specifications). The ACPI specification defines an interpreted language, ACPI Source Language (ASL), to enable the operating system to execute firmware-provided control methods for power management and configuration. To improve the ability for ASL writers to identify the host operating system version, ASL provides the Operating System Interface Level (_OSI). diff --git a/windows-driver-docs-pr/audio/acx-audio-class-extensions-overview.md b/windows-driver-docs-pr/audio/acx-audio-class-extensions-overview.md index 9e28570101..a5d16e75d0 100644 --- a/windows-driver-docs-pr/audio/acx-audio-class-extensions-overview.md +++ b/windows-driver-docs-pr/audio/acx-audio-class-extensions-overview.md @@ -1,11 +1,11 @@ --- -title: ACX Audio Class Extensions Overview +title: ACX audio class extensions overview description: This topic provides a high level overview of the ACX Audio Class Extensions. -ms.date: 07/28/2022 +ms.date: 04/19/2023 ms.localizationpriority: medium --- -# ACX Audio Class Extensions overview +# ACX audio class extensions overview >[!IMPORTANT] > Some information relates to a prerelease product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here. @@ -14,30 +14,30 @@ This topic provides a high level summary of the ACX Audio Class Extensions. ### ACX framework is built on top of the Windows Driver Framework -To allow audio drivers to be more reliable and offer the best possible experience for PC users, Audio Class eXtension (ACX) is now available in early preview. ACX defines a new Windows Driver Framework (WDF) class extension for the audio domain. For more information about WDF see [Introduction to Framework Objects](../wdf/introduction-to-framework-objects.md). Many WDF concepts such as WDF IO targets, are available in ACX. For more information about WDF IO targets, see [Introduction to I/O Targets](../wdf/introduction-to-i-o-targets.md). +To allow audio drivers to be more reliable and offer the best possible experience for PC users, Audio Class eXtension (ACX) is now available in early preview. ACX defines a new Windows Driver Framework (WDF) class extension for the audio domain. For more information about WDF see [Introduction to Framework Objects](../wdf/introduction-to-framework-objects.md). Many WDF concepts such as WDF IO targets, are available in ACX. For more information about WDF IO targets, see [Introduction to I/O Targets](../wdf/introduction-to-i-o-targets.md). ACX is built using the Kernel Mode Driver Framework (KMDF) and not the User Mode Driver Framework (UMDF) to avoid any latency associated with task-switching multiple times from User to Kernel mode while streaming. Portcls audio drivers, the current legacy model, are WDM, kernel mode based drivers. The use of the ACX framework makes it easy to create working audio drivers ‘out of the box’. For example, ACX supports default completion for most of its settings. This makes it easier for the driver to use the correct setting, yet still allows for customization. -The ACX framework exposes audio concepts as WDF objects that driver can interact with (stream, format, etc.). This allows for a consistent programming experience and enables a larger community of audio driver developers. +The ACX framework exposes audio concepts as WDF objects that driver can interact with (stream, format, etc.). This allows for a consistent programming experience and enables a larger community of audio driver developers. ### ACX goals The audio class extensions (ACX) have the following goals. -- Simplify the effort and know-how required to develop simple stand-alone audio drivers. +- Simplify the effort and know-how required to develop simple stand-alone audio drivers. - Reduce the amount of code that a 3rd party needs to develop. Fewer lines of code decreases maintenance and makes debugging easier. - Allows existing upper user-mode clients (services and apps) to run as is. - Simplify the power-pnp management of the audio stack drivers. -- No impact the overall performance, i.e., no additional/noticeable latency. +- No impact the overall performance, i.e., no additional/noticeable latency. - Simplify the effort required to develop multi-stack audio drivers. - Allow 3rd party driver to specify the locking mechanism to be used when streaming. - Uses the Microsoft component deployment isolation solution that makes drivers/APOs modules self-contained and reusable. -### ACX architecture +### ACX architecture -This diagram illustrates the acx architecture showing existing user mode apps and ACX objects in kernel mode and audio hardware at the bottom of the stack. In addition to the ACX objects, the driver developer has access to the WDF objects to take advantage of in their driver code, for example for power management. +This diagram illustrates the ACX architecture showing existing user mode apps and ACX objects in kernel mode and audio hardware at the bottom of the stack. In addition to the ACX objects, the driver developer has access to the WDF objects to take advantage of in their driver code, for example for power management. ![diagram illustrating the acx architecture showing user and kernel mode with WDF and ACX objects in kernel mode and audio hardware at the bottom of the stack.](images/audio-acx-architecture-overview.png) @@ -45,167 +45,66 @@ This diagram illustrates the acx architecture showing existing user mode apps an ACX is designed to co-exist with existing audio drivers, to allow for a flexible migration to new ACX drivers. -- Binary compatibility of exiting, unchanged (WDM-based) audio miniport drivers is maintained by existing legacy Windows class drivers. -- Only WaveRT based streaming is currently supported by ACX. -- Legacy PortCls/Ks and new ACX stacks run side-by-side. Using ACX does not force 3rd party to port their current audio drivers to the new model. As the model offers many advantages, 3rd parties may voluntarily opt to use it for their future audio development. +- Binary compatibility of exiting, unchanged (WDM-based) audio miniport drivers is maintained by existing legacy Windows class drivers. +- Only WaveRT based streaming is currently supported by ACX. +- Legacy PortCls/Ks and new ACX stacks run side-by-side. Using ACX does not force 3rd party to port their current audio drivers to the new model. As the model offers many advantages, 3rd parties may voluntarily opt to use it for their future audio development. -## ACX common definitions +## ACX common definitions -*Circuit* - A driver component representing a partial or full audio path. The circuit represents an existing endpoint and its capabilities. +*Circuit* - A driver component representing a partial or full audio path. The circuit represents an existing endpoint and its capabilities. *Stream* - A driver component that’s created to represent an audio stream, created by a Circuit. The Stream is composed of a list of Elements created based on the parent Circuit’s Elements. -*Stream Circuit* - the circuit in a multi-stack architecture (partial audio path) that directly interface with upper user-mode streaming service. +*Stream Circuit* - the circuit in a multi-stack architecture (partial audio path) that directly interface with upper user-mode streaming service. *Core Circuit* - The circuit in a multi-stack architecture (partial audio path) that gives the identity of the audio endpoint device. -*Element* - A subcomponent of a Circuit or Stream, representing an audio capability of the underline hardware. This could be a Volume, or Mute, or Jack element, or a Module element on a DSP circuit, etc. +*Element* - A subcomponent of a Circuit or Stream, representing an audio capability of the underline hardware. This could be a Volume, or Mute, or Jack element, or a Module element on a DSP circuit, etc. -*Endpoint Audio Path* - A single or group of Circuit objects connected together to represent a single audio endpoint. The Circuit objects must come from different device stacks belonging to the same or different drivers. +*Endpoint Audio Path* - A single or group of Circuit objects connected together to represent a single audio endpoint. The Circuit objects must come from different device stacks belonging to the same or different drivers. -## Summary of ACX Objects +### Summary of ACX objects -For a summary of the base ACX objects, see [Summary of ACX Objects](acx-summary-of-objects.md). +For a summary of the base ACX objects, see [Summary of ACX objects](acx-summary-of-objects.md). ## Sample ACX driver -The sample audio driver, SYSVAD will be updated to make use of ACX. When this sample is available, it will be linked here. - -## ACX Driver Logging - -Software tracing for drivers is usually based on Event Tracing for Windows (ETW), a kernel-level facility that logs trace messages for both kernel-mode and user-mode processes. As ACX drivers are WDF drivers, all of the WDF logging and eventing capabilities are available for ACX driver developers. - -### WPP - -Because ETW can be somewhat complicated to use, most driver developers use the Windows software trace preprocessor (WPP), which simplifies and enhances the process of instrumenting a driver for ETW tracing. - -ACX uses WPP logs for tracing and debugging. For more information, see [Using WPP Software Tracing in KMDF Drivers](../wdf/using-wpp-software-tracing-in-kmdf-drivers.md) and [Adding WPP Software Tracing to a Windows Driver](../devtest/adding-wpp-software-tracing-to-a-windows-driver.md). - -### In-Flight recorder (IFR) - -In-Flight recorder (IFR) is supported and can be viewed via WDFKD, RCDRKD or with the ACXKD debugger extension when it is available. For general information working with IFR logs, see [Using Inflight Trace Recorder (IFR) in KMDF and UMDF 2 Drivers](../devtest/using-wpp-recorder.md) and [Video: Accessing driver IFR logs without a debugger](../wdf/video--accessing-driver-ifr-logs-without-a-debugger.md) - -ACX logs key events using other ETW providers to simplify the visualization of these special events. - -### Adding logging to your driver - -3rd party drivers are highly encouraged to use WPP and ETW events as well. - -This example code, shows checking a return value and logging an appropriate error. - -```cpp - - // - // The driver uses this DDI to delete the circuits from the current device. - // - status = AcxDeviceRemoveCircuit(Device, devCtx->Speaker); - if (!NT_SUCCESS(status)) { DrvLogError(g_AudioDspLog, FLAG_INIT, L"Failed to remove speaker circuit, continuing with ReleaseHardware, %!STATUS!", status); } - status = AcxDeviceRemoveCircuit(Device, devCtx->MicArray); - if (!NT_SUCCESS(status)) { DrvLogError(g_AudioDspLog, FLAG_INIT, L"Failed to remove micarray circuit, continuing with ReleaseHardware, %!STATUS!", status); } - status = AcxDeviceRemoveCircuit(Device, devCtx->SpeakerHp); - if (!NT_SUCCESS(status)) { DrvLogError(g_AudioDspLog, FLAG_INIT, L"Failed to remove speakerHp circuit, continuing with ReleaseHardware, %!STATUS!", status); } - status = AcxDeviceRemoveCircuit(Device, devCtx->MicrophoneHp); - if (!NT_SUCCESS(status)) { DrvLogError(g_AudioDspLog, FLAG_INIT, L"Failed to remove microphoneHp circuit, continuing with ReleaseHardware, %!STATUS!", status); } - status = AcxDeviceRemoveCircuit(Device, devCtx->HDMI); - if (!NT_SUCCESS(status)) { DrvLogError(g_AudioDspLog, FLAG_INIT, L"Failed to remove HDMI circuit, continuing with ReleaseHardware, %!STATUS!", status); } -``` - -The featured version of the Toaster driver sample code provides examples of WMI tracing as well as reusable tracing code. For more information about the Toaster sample, see [Toaster Sample Driver](/samples/microsoft/windows-driver-samples/toaster-sample-driver/). - -### Recommendations for ACX Driver logging - -To improve the reliability of your ACX driver consider the following behaviors for logging. - -- Unexpected return values from stream buffer IO or other regular signal processing activity. -- Unexpected power states or power state transitions. -- Errors related to calls made during updates or re-installation. -- Other behaviors that may lead to “no audio” could be considered for logging. - -### Using the WMI Tracing debugger extensions - -To view trace events in the debugger, use the WMI extension, Wmitrace.dll. It contains a library of functions designed to control and view WMI event tracing. For more information, see [WMI Tracing Extensions (Wmitrace.dll)](../debugger/wmi-tracing-extensions--wmitrace-dll-.md). - - -## ACX driver debugging - -ACX drivers are WDF drivers, so the debugging techniques described for WDF drivers, apply to ACX drivers. See the following topics for information on debugging WDF drivers. - -#### General information about the debugging tools - -[Debugging Tools for Windows (WinDbg, KD, CDB, NTSD)](../debugger/index.md) - -#### KMDF debugging - -- [Summary of Debugger Extensions in Wdfkd.dll](../wdf/debugger-extensions-for-kmdf-drivers.md) - -- This walk through uses the traditional Sysvad audio driver, but illustrates some techniques that may be help to ACX drivers. -[Debug Drivers - Step by Step Lab (Sysvad Kernel Mode)](../debugger/debug-universal-drivers--kernel-mode-.md) - -#### Video Walkthroughs - -- [Video: Debugging your driver with WDF source code](../wdf/video--debugging-your-driver-with-wdf-source-code.md) -- [Video Series: Debugging Kernel-Mode Driver Framework Drivers](../wdf/debugging-kernel-mode-driver-framework-drivers.md) - -#### ACX kernel debugger extension library (AcxKd.dll) - -To aid debugging, ACX has a companion kernel debugger extension library (AcxKd.dll). This library aids developers in tracking down issue on single and multi-stack audio paths. The kd extension allows developer to look inside ACX structures. - ->[!NOTE] -> This debugger extension is under development and information will be provided here when it is available. +A simple ACX sample driver is available to view and download on GitHub in the develop branch - [https://github.com/microsoft/Windows-driver-samples/tree/develop/audio/Acx/Samples](https://github.com/microsoft/Windows-driver-samples/tree/develop/audio/Acx/Samples). ## Driver Verifier The use of driver verifier is encouraged for all Windows drivers, including ACX drivers. Use driver verifier to surface latent errors, decrease the power consumption and increase the reliability of your driver. For more information, see [Driver Verifier](../devtest/driver-verifier.md). - ## ACX Multi-stack driver standardized cross communications -It is common for the audio path to go through multiple hardware components handled by different driver stacks to create a complete audio experience. It is typical for a system to have the DSP, CODEC and AMP functionality implemented by different audio technology vendors. +It is common for the audio path to go through multiple hardware components handled by different driver stacks to create a complete audio experience. It is typical for a system to have the DSP, CODEC and AMP functionality implemented by different audio technology vendors. -In a multi-stack architecture without a well-defined standard, each vendor is forced to define its own proprietary interface and communications protocol. It is a goal of ACX to facilitate the development of multi-stack audio drivers by taking ownership of the synchronization between these stacks and providing a simple re-usable pattern for drivers communicate with each other. +In a multi-stack architecture without a well-defined standard, each vendor is forced to define its own proprietary interface and communications protocol. It is a goal of ACX to facilitate the development of multi-stack audio drivers by taking ownership of the synchronization between these stacks and providing a simple re-usable pattern for drivers communicate with each other. -For more information, see [ACX multi stack cross driver communications](acx-audio-multi-stack.md). +For more information, see [ACX multi stack cross driver communications](acx-multi-stack.md). ## ACX reference documentation -The following acx headers have preliminary reference documentation available. - -Just like WDF drivers, DEVICE and DRIVER are used to initialize the base driver. - -- [acxdevice.h](/windows-hardware/drivers/ddi/acxdevice/) -- [acxdriver.h](/windows-hardware/drivers/ddi/acxdriver/) - -Pins, streams and circuits are used to route audio signals. +For information about the header level ACX reference documentation, see [ACX reference documentation](acx-reference.md). -- [acxpin.h](/windows-hardware/drivers/ddi/acxpin/) -- [acxstreams.h](/windows-hardware/drivers/ddi/acxstreams/) -- [acxcircuit.h](/windows-hardware/drivers/ddi/acxcircuit/) -- [acxtargets.h](/windows-hardware/drivers/ddi/acxtargets/) - -The data formats are controlled using this header. - -- [acxdataformat.h](/windows-hardware/drivers/ddi/acxdataformat/) - -The acxelements header provides access to specific audio system elements, such as volume, mute, peakmeter and the keyword spotter. +## See also -- [acxelements.h](/windows-hardware/drivers/ddi/acxelements/) +[Summary of ACX objects](acx-summary-of-objects.md) -Events and requests allow for notification. +[ACX reference documentation](acx-reference.md) -- [acxevents.h](/windows-hardware/drivers/ddi/acxevents/) -- [acxrequest.h](/windows-hardware/drivers/ddi/acxrequest/) +[ACX version information](acx-version-overview.md) -An object bag, which can be used to store and retrieve configuration information and is defined in acxmisc. +[ACX logging and debugging](acx-logging-and-debugging.md) -- [acxmisc.h](/windows-hardware/drivers/ddi/acxmisc/) - -The ACX manager is used for supporting composite audio endpoints. +[ACX targets and driver synchronization](acx-targets.md) -- [acxmanager.h](/windows-hardware/drivers/ddi/acxmanager/) +[ACX IO request packet IRPs](acx-irps.md) +[ACX device enumeration](acx-device-enumeration.md) -## See also +[ACX power management](acx-power-management.md) -[Summary of ACX Objects](acx-summary-of-objects.md) +[ACX multi stack cross driver communications](acx-multi-stack.md) -[ACX multi stack cross driver communications](acx-audio-multi-stack.md) \ No newline at end of file +[ACX streaming](acx-streaming.md) diff --git a/windows-driver-docs-pr/audio/acx-audio-multi-stack.md b/windows-driver-docs-pr/audio/acx-audio-multi-stack.md deleted file mode 100644 index a42473a067..0000000000 --- a/windows-driver-docs-pr/audio/acx-audio-multi-stack.md +++ /dev/null @@ -1,581 +0,0 @@ ---- -title: ACX Audio multi stack cross driver communications -description: This topic provides a high level summary of the multi stack cross driver communications. -ms.date: 08/17/2022 -ms.localizationpriority: medium ---- - -# ACX multi stack cross driver communications - ->[!IMPORTANT] -> Some information relates to a prerelease product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here. - -This topic provides a summary of the Audio Class eXtensions (ACX) multi stack cross driver communications. - -For general information about the ACX, see [ACX Audio Class Extensions Overview](acx-audio-class-extensions-overview.md) and [Summary of ACX Objects](acx-summary-of-objects.md). - - -## Single-Stack Audio Drivers - -Legacy PortCls and KS audio class drivers only support “single stack” audio drivers. The legacy audio framework communicates and interface with only one miniport driver. It is up to the miniport driver to manage the communication and synchronization with other driver stacks when necessary. - -ACX fully supports single-stack audio drivers. Audio developers can replace their current Portcls and KS miniport driver with an ACX-based driver while keeping the same behavior in relation with other stacks. Although if the audio subsystem uses multi-audio stacks, a better approach would be use to use the multi-stack support in ACX, and let ACX synchronize all these stacks together, as described in the next section of this topic. - - -## Multi-Stack Audio Drivers - Componentization - -It is very common for the audio path to go through multiple hardware components handled by different driver stacks to create a complete audio experience. It is typical for a system to have the DSP, CODEC and AMP functionality implemented by different audio technology vendors as shown in the following diagram. - -![diagram illustrating three boxes with arrows to the left of a DSP, CODEC and AMP](images/audio-acx-multi-stack-multiple-hw.png) - -In a multi-stack architecture without a well-defined standard, each vendor is forced to define its own proprietary interface and communications protocol. It is a goal of ACX to facilitate the development of multi-stack audio drivers by taking ownership of the synchronization between these stacks and providing a simple re-usable pattern for drivers communicate with each other. - -Using ACX, the example system DSP, CODEC and AMP hardware design can be supported with the following software architecture. - -![diagram illustrating the acx architecture showing three drivers each with an acx stack for a DSP, CODEC and AMP](images/audio-acx-multi-stack-multiple-hw-three-drivers.png) - -Note that any type of component type instead of the shown DSP, CODEC and AMP, could be used, as ACX does not depend on any specific component type, or specific arrangements of components. - -Third party drivers communicate with each other via ACX with a well-defined protocol. One advantage of this approach is that a single stack could be replaced with another one from a different vendor without requiring changes to the adjacent software stacks. One of the primary goals of the audio class extensions (ACX) framework is to simplify the effort required to develop multi-stack audio drivers assembled from components from different vendors. - -## ACX Targets - -ACX uses [WdfIoTarget](/windows-hardware/drivers/ddi/wdfiotarget/) to facilitate communications between ACX objects, circuits, pins, streams, elements and circuit factories. WdfIoTarget is an existing WDF abstraction to facilitate the communication between two different stacks. - -Drivers use [AcxTargetCircuit](/windows-hardware/drivers/ddi/acxtargets/) to communicate with a remote circuit exposed by a different stack. AcxTargetCircuit is implemented using a WdfIoTarget. - -Drivers use [AcxTargetPin](/windows-hardware/drivers/ddi/acxpin/) to communicate with a remote circuit’s pin exposed by a different stack. AcxTargetPin is implemented using a WdfIoTarget to send messages to the remote pin entity. - -Drivers use [AcxTargetStream](/windows-hardware/drivers/ddi/acxstreams/) to communicate with a remote circuit’s stream exposed by a different stack. AcxTargetStream is implemented using a WdfIoTarget to create a remote stream and change the state of the remote stream. - -Drivers use [AcxTargetElement](/windows-hardware/drivers/ddi/acxtargets/) to communicate with a remote circuit’s element exposed by a different stack. AcxTargetElement is implemented using a WdfIoTarget to send messages to the remote element entity. - -Drivers use [AcxTargetFactoryCircuit](/windows-hardware/drivers/ddi/acxtargets/) to communicate with a remote circuit factory instance. AcxTargetFactoryCircuit is implemented using a WdfTarget to send messages to the remote circuit factory. - -To interact with the remote circuit, each of the ACX types listed above supports: - -- properties -- methods -- events - -All these types are built on top of the [WdfIoTarget](/windows-hardware/drivers/ddi/wdfiotarget/) object types. - -This diagram shows the ACX target architecture and the inheritance from the WDF Driver and Device objects. - -![diagram illustrating the acx target architecture showing WDFDRIVER, WDFDEVICE, and under that ACXTARGET, ACXSTREAM ACXSTREAMFACTORY with the lowest layer showing ACXTARGETELEMENT and ACXTARGETPIN](images/audio-acx-multi-stack-acxtarget-objects.png) - - -## ACX Driver Synchronization and Serialization - -The term synchronization is a general term, and it is used to reference the operations needed to share resources (memory, I/O, etc.) between multiple concurrent clients. - -The term serialization is used to reference one type of synchronization for one type of object (I/O requests, callbacks, etc.). - -ACX Drivers are WDF Drivers, which means that the synchronization of ACX Drivers is based on the synchronization capabilities of WDF: - -- The use of reference counts and the hierarchical object model. -- Driver-configurable flow control for I/O queues. -- Object presentation lock for device objects and I/O queues. -- Automatic serialization of Plug and Play and power callbacks. - -For an in-depth description of Synchronization and Serialization, see [Using Automatic Synchronization](../wdf/using-automatic-synchronization.md). For a more complete explanation, see the [Developing Drivers with Windows Driver Foundation](../wdf/developing-drivers-with-wdf.md) Microsoft Press Book. - -WDF supports the following synchronization scopes: - -- No scope (default in KMDF). -- Device scope, WDF acquires the device object presentation lock to serialize operations. - -The default ACX queue is a passive, serial queue with no locking. The driver must complete the I/O operation before the next one is delivered. - -ACX doesn’t support the queue scope option. With this option the driver serializes I/O on a specific queue. Different queues may have different synchronization scopes. - -ACX doesn’t support device scope serialization. By default, ACX serializes requests using a serial I/O queue with no locking. Every circuit and stream object have its own dedicated queue. For more info about streaming I/Os please see the ACX Streaming topic. - -If a driver holds a lock, it should never call (explicitly or implicitly) code outside its control until the lock is released. - -For historical reference, the original PortCls uses a synchronization scope like the WDF device scope synchronization, where all I/O for any audio sub-devices created on this device go through the same serialization lock. This type of serialization was, and still is, the cause of various glitches. In later versions of Windows 10 (Version 1511 - TH2) PortCls was updated to use a different lock for stream position I/O requests. - -## IRP/Request Dispatching - -An ACX client specifies an action via a driver request (IRP). For general information about IRPs, see, [I/O request packets](../gettingstarted/i-o-request-packets.md) and [Packet-Driven I/O with Reusable IRPs](../kernel/packet-driven-i-o-with-reusable-irps.md). - -The client sends this request to a circuit/pin/element/stream by using the circuit or stream handle. The request ID is a triplet: - -- set (guid), -- id/index (ulong) -- optional pin-id/node-id (ulong) value. - -At creation time the driver can optionally associates properties/methods/events with one of more of following objects: - -- pin -- circuit -- stream -- element - -Each property/method/event is identified by an ID and a callback handler. By default, ACX defines all the properties/methods/events required by KS-clients (user-mode layers), thus drivers do not need to redefine them. Drivers only need to define their custom properties/methods/events. - -When ACX receives an ACX/KS style IoCtrl request, it validates the request and locks the caller’s buffers in memory. This validation and buffer lock down is done in a WDM preprocess callback that ACX registered at initialization time. During this phase, the ACX adds its own completion callback to the WDM IRP before forwarding it back to WDF for normal dispatching. The completion callback gives ACX an opportunity to add/inject any compatibility workarounds as needed. - -Next WDF invokes the dynamic dispatch IRP callback, in this callback ACX/driver (optionally) associates a WDF queue with the request. In this callback ACX locates the target ACX object: circuit, pin, circuit-element or stream using the handle on which this request was sent, and the optional pin-id/node-id/circuit-element within the request. - -In an audio composite device it is possible that the target object (circuit-only) may be located on a different stack than the one on which the request is originally sent on. In addition, a request may need to act on multiple stacks, an example of this, is a stream change state. - -After the target has been identified, ACX checks if the target circuit/stream-object specifies an override for the default processing queue, if not, ACX uses the default queue associated with current handle. The ACX/driver then instructs WDF to insert the request into the either the specified or the default queue. - -Next WDF invokes the in-caller process callback if present. ACX doesn’t need/use the in-caller process callback because it already locked the buffers in memory in the preprocess callback. Thus, ACX informs WDF to not invoke the in-process callback after specifying the target queue for the request. - -### Secondary queue usage - -The default ACX queue is a power-managed, serial, no-locking queue. The driver should move any request taking an undetermined amount of time into a secondary queue. The driver managed queue could be a manual-passive queue, where the driver can hold on to these requests until it is ready to complete them later. - -### Power reference requests - -ACX automatically power up the device before dispatching a request to the driver. This is done implicitely by using a WDF power managed queues. This creates a behavior similar to portcls. That is, a power reference is taken, before dispatching the request. - -### Invoking the queue’s dispatch handler - -Next WDF takes a power reference and invokes the queue’s dispatch handler. The default queue which is associated with the ACX handler checks for any preprocess overrides, and if present, ACX invokes the registered driver’s preprocess callback. ACX allows the driver to specify overrides based on the type of request (property, event, and method) and (optionally) request IDs. - -If a preprocess callback was specified, after ACX invokes the callback, the request is owned by the driver. The driver may complete the request or forward it back to ACX for normal dispatching. - -If a preprocess callback was not specified, or if the driver gives back the request to ACX, ACX retrieves the target ACX object and locates the declared property/event/method’s callback. It then invokes the callback passing the WDF request and the target ACX Object (circuit/stream/circuit-element). - -Next ACX (or for custom properties, the driver) performs the requested action and completes the request, or if the request takes an undetermined amount of time, the driver can move the request to a secondary queue. The driver is responsible for serializing and completing any active pending requests. - -This diagram illustrates the typical request dispatch workflow. - -![diagram illustrating dispatch workflow showing and audio service, WDF, ACX and a driver](images/audio-acx-dispatch-workflow-1.png) - -This diagram illustrates the dispatch workflow when driver has an ACX preprocess callback defined, although in the end the request is handled by the ACX framework. - -![diagram illustrating dispatch workflow showing and audio service, WDF, ACX and a driver with a preprocess callback](images/audio-acx-dispatch-workflow-2.png) - - -### ACX Targets Communications Example - Circuit - -This example code shows the use of AcxTargetCircuit and AcxTargetCircuitGetWdfIoTarget to communicate with a remote circuit exposed by a different stack. For more information about ACX Circuits, see [acxcircuit.h](/windows-hardware/drivers/ddi/acxcircuit/). - -This fairly complex aggregator locates circuits and then creates an ioTarget using AcxTargetCircuitGetWdfIoTarget. It then sets custom WDF send options and asynchronously sends the request. Lastly, it checks the status of the send to confirm the request was sent. - -```cpp -NTSTATUS -Aggregator_SendModuleCommand( - _In_ PAGGREGATOR_RENDER_CIRCUIT_CONTEXT CircuitCtx, - _In_ ACX_REQUEST_PARAMETERS Params, - _Out_ ULONG_PTR * OutSize - ) -{ - NTSTATUS status = STATUS_NOT_SUPPORTED; - PKSAUDIOMODULE_PROPERTY moduleProperty = nullptr; - ULONG aggregationDeviceIndex = 0; - PLIST_ENTRY ple; - - *OutSize = 0; - - moduleProperty = CONTAINING_RECORD(Params.Parameters.Property.Control, KSAUDIOMODULE_PROPERTY, ClassId);; - aggregationDeviceIndex = AUDIOMODULE_GET_AGGDEVICEID(moduleProperty->InstanceId); - - ple = CircuitCtx->AggregatorCircuit->AggregatorEndpoint->AudioPaths[aggregationDeviceIndex]->TargetCircuitList.Flink; - while (ple != &CircuitCtx->AggregatorCircuit->AggregatorEndpoint->AudioPaths[aggregationDeviceIndex]->TargetCircuitList) - { - PAUDIO_CIRCUIT circuit = (PAUDIO_CIRCUIT)CONTAINING_RECORD(ple, AUDIO_CIRCUIT, ListEntry); - - if (circuit->Modules) - { - for(ULONG i = 0; i < circuit->Modules->Count; i++) - { - PACX_AUDIOMODULE_DESCRIPTOR descriptor = ((PACX_AUDIOMODULE_DESCRIPTOR)(circuit->Modules + 1) + i); - - // we've identified which aggregation device this call is targeting, - // now locate which circuit implements this module. Within an aggregated device, - // the module class id + instance id must uniquely identify a module. There should - // never be duplicates. - if (IsEqualGUIDAligned(descriptor->ClassId, moduleProperty->ClassId) && - descriptor->InstanceId == moduleProperty->InstanceId) - { - WDFREQUEST request = NULL; - WDF_REQUEST_SEND_OPTIONS sendOptions; - WDF_OBJECT_ATTRIBUTES attributes; - WDFIOTARGET ioTarget; - - // We've now identified which aggregated device this call is targeting. - // The cached module information contains the ID adjusted with the aggregation device - // index. remove the aggregation device index before forwarding the call to the aggregated circuit. - moduleProperty->InstanceId = AUDIOMODULE_GET_INSTANCEID(moduleProperty->InstanceId); - - ioTarget = AcxTargetCircuitGetWdfIoTarget(circuit->AcxTargetCircuit); - - WDF_OBJECT_ATTRIBUTES_INIT(&attributes); - attributes.ParentObject = CircuitCtx->AggregatorCircuit->Circuit; - status = WdfRequestCreate(&attributes, ioTarget, &request); - if (!NT_SUCCESS(status)) - { - goto exit; - } - - status = AcxTargetCircuitFormatRequestForProperty(circuit->AcxTargetCircuit, request, &Params); - if (!NT_SUCCESS(status)) - { - goto exit; - } - - WDF_REQUEST_SEND_OPTIONS_INIT(&sendOptions, WDF_REQUEST_SEND_OPTION_SYNCHRONOUS); - WDF_REQUEST_SEND_OPTIONS_SET_TIMEOUT(&sendOptions, WDF_REL_TIMEOUT_IN_SEC(REQUEST_TIMEOUT_SECONDS)); - - // Whether WdfRequestSend succeeds or fails, we return the status & information, so - // there's no need to inspect the result. - WdfRequestSend(request, ioTarget, &sendOptions); - status = WdfRequestGetStatus(request); - *OutSize = WdfRequestGetInformation(request); - - WdfObjectDelete(request); - goto exit; - } - } - } - - ple = ple->Flink; - } - - status = STATUS_SUCCESS; - -exit: - return status; -} -``` - -### ACX Targets Communications Example - Pin - -This example code shows the use of AcxTargetPin to communicate with a remote circuit’s pin exposed by a different stack. For more information about ACX Pin, see [acxpin.h](/windows-hardware/drivers/ddi/acxpin/). - -It selects the last Volume and Mute elements that are both present in the same circuit in the Endpoint Path. - -```cpp -NTSTATUS FindDownstreamVolumeMute( - _In_ ACXCIRCUIT Circuit, - _In_ ACXTARGETCIRCUIT TargetCircuit -) -{ - NTSTATUS status; - PDSP_CIRCUIT_CONTEXT circuitCtx; - ACX_REQUEST_PARAMETERS params; - WDF_REQUEST_SEND_OPTIONS sendOptions; - WDF_OBJECT_ATTRIBUTES attributes; - WDF_REQUEST_REUSE_PARAMS reuseParams; - - circuitCtx = GetDspCircuitContext(Circuit); - - // - // Note on behavior: This search algorithm will select the last Volume and Mute elements that are both - // present in the same circuit in the Endpoint Path. - // This logic could be updated to select the last Volume and Mute elements, or the first or last - // Volume or the first or last Mute element. - // - - // - // First look through target's pins to determine if there's another circuit downstream. - // If there is, we'll look at that circuit for volume/mute. - // - for (ULONG pinIndex = 0; pinIndex < AcxTargetCircuitGetPinsCount(TargetCircuit); ++pinIndex) - { - ACXTARGETPIN targetPin = AcxTargetCircuitGetTargetPin(TargetCircuit, pinIndex); - ULONG targetPinFlow = 0; - ACX_REQUEST_PARAMETERS_INIT_PROPERTY(¶ms, - KSPROPSETID_Pin, - KSPROPERTY_PIN_DATAFLOW, - AcxPropertyVerbGet, - AcxItemTypePin, - AcxTargetPinGetId(targetPin), - nullptr, 0, - &targetPinFlow, - sizeof(targetPinFlow)); - - RETURN_NTSTATUS_IF_FAILED(SendProperty(targetPin, ¶ms, nullptr)); - - // - // Searching for the downstream pins. For Render, these are the dataflow out pins - // - if (circuitCtx->IsRenderCircuit && targetPinFlow != KSPIN_DATAFLOW_OUT) - { - continue; - } - else if (!circuitCtx->IsRenderCircuit && targetPinFlow != KSPIN_DATAFLOW_IN) - { - continue; - } - - // Get the target pin's physical connection. We'll do this twice: first to get size and allocate, second to get the connection - PKSPIN_PHYSICALCONNECTION pinConnection = nullptr; - auto connection_free = scope_exit([&pinConnection]() - { - if (pinConnection) - { - ExFreePool(pinConnection); - pinConnection = nullptr; - } - }); - - ULONG pinConnectionSize = 0; - ULONG_PTR info = 0; - for (ULONG i = 0; i < 2; ++i) - { - ACX_REQUEST_PARAMETERS_INIT_PROPERTY(¶ms, - KSPROPSETID_Pin, - KSPROPERTY_PIN_PHYSICALCONNECTION, - AcxPropertyVerbGet, - AcxItemTypePin, - AcxTargetPinGetId(targetPin), - nullptr, 0, - pinConnection, - pinConnectionSize); - - status = SendProperty(targetPin, ¶ms, &info); - - if (status == STATUS_BUFFER_OVERFLOW) - { - // Pin connection already allocated, so how did this fail? - RETURN_NTSTATUS_IF_TRUE(pinConnection != nullptr, status); - - pinConnectionSize = (ULONG)info; - pinConnection = (PKSPIN_PHYSICALCONNECTION)ExAllocatePool2(POOL_FLAG_NON_PAGED, pinConnectionSize, DRIVER_TAG); - // RETURN_NTSTATUS_IF_NULL_ALLOC causes compile errors - RETURN_NTSTATUS_IF_TRUE(pinConnection == nullptr, STATUS_INSUFFICIENT_RESOURCES); - } - else if (!NT_SUCCESS(status)) - { - // There are no more connected circuits. Continue with processing this circuit. - break; - } - } - - if (!NT_SUCCESS(status)) - { - // There are no more connected circuits. Continue handling this circuit. - break; - } - - ACXTARGETCIRCUIT nextTargetCircuit; - RETURN_NTSTATUS_IF_FAILED(CreateTargetCircuit(Circuit, pinConnection, pinConnectionSize, &nextTargetCircuit)); - auto circuit_free = scope_exit([&nextTargetCircuit]() - { - if (nextTargetCircuit) - { - WdfObjectDelete(nextTargetCircuit); - nextTargetCircuit = nullptr; - } - }); - - RETURN_NTSTATUS_IF_FAILED_UNLESS_ALLOWED(FindDownstreamVolumeMute(Circuit, nextTargetCircuit), STATUS_NOT_FOUND); - if (circuitCtx->TargetVolumeMuteCircuit == nextTargetCircuit) - { - // The nextTargetCircuit is the owner of the volume/mute target elements. - // We will delete it when the pin is disconnected. - circuit_free.release(); - - // We found volume/mute. Return. - return STATUS_SUCCESS; - } - - // There's only one downstream pin on the current targetcircuit, and we just processed it. - break; - } - - // - // Search the target circuit for a volume or mute element. - // This sample code doesn't support downstream audioengine elements. - // - for (ULONG elementIndex = 0; elementIndex < AcxTargetCircuitGetElementsCount(TargetCircuit); ++elementIndex) - { - ACXTARGETELEMENT targetElement = AcxTargetCircuitGetTargetElement(TargetCircuit, elementIndex); - GUID elementType = AcxTargetElementGetType(targetElement); - - if (IsEqualGUID(elementType, KSNODETYPE_VOLUME) && - circuitCtx->TargetVolumeHandler == nullptr) - { - // Found Volume - circuitCtx->TargetVolumeHandler = targetElement; - } - if (IsEqualGUID(elementType, KSNODETYPE_MUTE) && - circuitCtx->TargetMuteHandler == nullptr) - { - // Found Mute - circuitCtx->TargetMuteHandler = targetElement; - } - } - - if (circuitCtx->TargetVolumeHandler && circuitCtx->TargetMuteHandler) - { - circuitCtx->TargetVolumeMuteCircuit = TargetCircuit; - return STATUS_SUCCESS; - } - - // - // If we only found one of volume or mute, keep searching for both - // - if (circuitCtx->TargetVolumeHandler || circuitCtx->TargetMuteHandler) - { - circuitCtx->TargetMuteHandler = circuitCtx->TargetVolumeHandler = nullptr; - } - - return STATUS_NOT_FOUND; -} -``` - -### ACX Targets Communications Example - Stream - -This example code shows the use of AcxTargetStream to communicate with a remote circuit’s stream. For more information about ACX Streams, see [acxstreams.h](/windows-hardware/drivers/ddi/acxstreams/). - -```cpp - - NTSTATUS status; - PRENDER_DEVICE_CONTEXT devCtx; - WDF_OBJECT_ATTRIBUTES attributes; - ACXSTREAM stream; - STREAM_CONTEXT * streamCtx; - ACXELEMENT elements[2] = {0}; - ACX_ELEMENT_CONFIG elementCfg; - ELEMENT_CONTEXT * elementCtx; - ACX_STREAM_CALLBACKS streamCallbacks; - ACX_RT_STREAM_CALLBACKS rtCallbacks; - CRenderStreamEngine * streamEngine = NULL; - - PAGED_CODE(); - UNREFERENCED_PARAMETER(Pin); - UNREFERENCED_PARAMETER(SignalProcessingMode); - UNREFERENCED_PARAMETER(VarArguments); - - // This unit-test added support for RAW and DEFAULT. - ASSERT(IsEqualGUID(*SignalProcessingMode, AUDIO_SIGNALPROCESSINGMODE_RAW) || - IsEqualGUID(*SignalProcessingMode, AUDIO_SIGNALPROCESSINGMODE_DEFAULT)); - - devCtx = GetRenderDeviceContext(Device); - ASSERT(devCtx != NULL); - - // - // Init streaming callbacks. - // - ACX_STREAM_CALLBACKS_INIT(&streamCallbacks); - streamCallbacks.EvtAcxStreamPrepareHardware = EvtStreamPrepareHardware; - streamCallbacks.EvtAcxStreamReleaseHardware = EvtStreamReleaseHardware; - streamCallbacks.EvtAcxStreamRun = EvtStreamRun; - streamCallbacks.EvtAcxStreamPause = EvtStreamPause; - streamCallbacks.EvtAcxStreamAssignDrmContentId = EvtStreamAssignDrmContentId; - - status = AcxStreamInitAssignAcxStreamCallbacks(StreamInit, &streamCallbacks); - if (!NT_SUCCESS(status)) - { - ASSERT(FALSE); - goto exit; - } - - // - // Init RT streaming callbacks. - // - ACX_RT_STREAM_CALLBACKS_INIT(&rtCallbacks); - rtCallbacks.EvtAcxStreamGetHwLatency = EvtStreamGetHwLatency; - rtCallbacks.EvtAcxStreamAllocateRtPackets = EvtStreamAllocateRtPackets; - rtCallbacks.EvtAcxStreamFreeRtPackets = EvtStreamFreeRtPackets; - rtCallbacks.EvtAcxStreamSetRenderPacket = R_EvtStreamSetRenderPacket; - rtCallbacks.EvtAcxStreamGetCurrentPacket = EvtStreamGetCurrentPacket; - rtCallbacks.EvtAcxStreamGetPresentationPosition = EvtStreamGetPresentationPosition; - - status = AcxStreamInitAssignAcxRtStreamCallbacks(StreamInit, &rtCallbacks); - if (!NT_SUCCESS(status)) - { - ASSERT(FALSE); - goto exit; - } - - // - // Create the stream. - // - WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attributes, STREAM_CONTEXT); - attributes.EvtCleanupCallback = EvtStreamCleanup; - attributes.EvtDestroyCallback = EvtStreamDestroy; - status = AcxRtStreamCreate(Device, Circuit, &attributes, &StreamInit, &stream); - if (!NT_SUCCESS(status)) - { - ASSERT(FALSE); - goto exit; - } - - // START-TESTING: inverted create-stream sequence. - { - ACXSTREAMBRIDGE bridge = NULL; - ACXPIN bridgePin = NULL; - ACXTARGETSTREAM targetStream = NULL; - ACX_STREAM_BRIDGE_CONFIG bridgeCfg; - - ACX_STREAM_BRIDGE_CONFIG_INIT(&bridgeCfg); - bridgeCfg.InModesCount = 0; // no in-modes. this stream-bridge is manually managed. - bridgeCfg.InModes = NULL; - bridgeCfg.OutMode = NULL; // no mode, i.e., default (1st) and raw (2nd). - bridgeCfg.Flags |= AcxStreamBridgeInvertChangeStateSequence; - - WDF_OBJECT_ATTRIBUTES_INIT(&attributes); - attributes.ParentObject = WdfGetDriver(); // bridge is deleted by driver obj in case of error. - - status = AcxStreamBridgeCreate(Circuit, &attributes, &bridgeCfg, &bridge); - if (!NT_SUCCESS(status)) - { - ASSERT(FALSE); - goto exit; - } - - ... - - status = AcxStreamBridgeAddStream(bridge, stream); - if (!NT_SUCCESS(status)) - { - ASSERT(FALSE); - goto exit; - } - - // Get the Target Stream - targetStream = AcxStreamBridgeGetTargetStream(bridge, stream); - if (targetStream == NULL) - { - ASSERT(FALSE); - goto exit; - } -``` - -### ACX Targets Communications Example - Element - -This example code shows the use of AcxTargetElement to communicate with a circuit’s element. For more information about the ACX Targets, see [acxtargets.h](/windows-hardware/drivers/ddi/acxtargets/). - -```cpp - _In_ ACXCIRCUIT Circuit, - _In_ ACXTARGETCIRCUIT TargetCircuit - -... - - // - // Search the target circuit for a volume or mute element. - // This sample code doesn't support downstream audioengine elements. - // - for (ULONG elementIndex = 0; elementIndex < AcxTargetCircuitGetElementsCount(TargetCircuit); ++elementIndex) - { - ACXTARGETELEMENT targetElement = AcxTargetCircuitGetTargetElement(TargetCircuit, elementIndex); - GUID elementType = AcxTargetElementGetType(targetElement); - - if (IsEqualGUID(elementType, KSNODETYPE_VOLUME) && - circuitCtx->TargetVolumeHandler == nullptr) - { - // Found Volume - circuitCtx->TargetVolumeHandler = targetElement; - } - if (IsEqualGUID(elementType, KSNODETYPE_MUTE) && - circuitCtx->TargetMuteHandler == nullptr) - { - // Found Mute - circuitCtx->TargetMuteHandler = targetElement; - } - } -``` - -## See also - -[ACX Audio Class Extensions Overview](acx-audio-class-extensions-overview.md) - -[Summary of ACX Objects](acx-summary-of-objects.md) \ No newline at end of file diff --git a/windows-driver-docs-pr/audio/acx-device-enumeration.md b/windows-driver-docs-pr/audio/acx-device-enumeration.md new file mode 100644 index 0000000000..ed3b324bf7 --- /dev/null +++ b/windows-driver-docs-pr/audio/acx-device-enumeration.md @@ -0,0 +1,154 @@ +--- +title: ACX device enumeration +description: This topic provides a summary of the ACX device enumeration, startup and shutdown, and device rebalance. +ms.date: 04/14/2023 +ms.localizationpriority: medium +--- + +# ACX device enumeration + +>[!IMPORTANT] +> Some information relates to a prerelease product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here. + +This topic discusses ACX device enumeration, startup and shutdown, and device rebalance. For a general overview of ACX, see [ACX audio class extensions overview](acx-audio-class-extensions-overview.md). For information about ACX power management and PnP, see [ACX power management](acx-power-management.md). + +## ACX device enumeration and startup for static audio devices + +To learn about how ACX startup works, the following scenario will be described. + +- An audio device is represented by a single circuit. +- An audio/circuit lifetime is tied to the PnP device lifetime. +- A single device can create multiple circuits for different audio devices. +- KMDF kernel-mode environment. + +The sequence of start up is: + +- WDM DriverEntry. Driver-scoped. + - Init tracing. + - Optionally register for unload. + - Create WDFDRIVER. + - Call ACX to do any post driver init. + - Optionally do any post driver init. + - For more information, see [DriverEntry for WDF Drivers routine](../wdf/driverentry-for-kmdf-drivers.md). + +- WDF DeviceAdd. Device-scoped. + - Call ACX to init the device init context. + - Create device. + - Call ACX to do any post device init. + - Optionally do any post device init. + - For more information, see [EVT_WDF_DRIVER_DEVICE_ADD callback function](/windows-hardware/drivers/ddi/wdfdriver/nc-wdfdriver-evt_wdf_driver_device_add). + +- WDF PrepareHardware. Device-scoped. + - Create and init hardware resources (for interrupts and threads, register them with ACX). + - Create one or more circuits (one time creation). + - Create an AcxCircuitInit Context. + - Add callbacks. + - Create an AcxCircuit. + - Optionally do any post circuit init. + - Register the circuit with AcxDeviceAddCircuit. + - For more information, see [EVT_WDF_DEVICE_PREPARE_HARDWARE callback function](/windows-hardware/drivers/ddi/wdfdevice/nc-wdfdevice-evt_wdf_device_prepare_hardware). + +- WDF Device D0 Entry callback. Device-scoped. + - For more information, see [EVT_WDF_DEVICE_D0_ENTRY callback function](/windows-hardware/drivers/ddi/wdfdevice/nc-wdfdevice-evt_wdf_device_d0_entry). + +- ACX invokes the [EvtAcxCircuitPowerUp callback](/windows-hardware/drivers/ddi/acxcircuit/nc-acxcircuit-evt_acx_circuit_power_up) on all the circuits. Circuit-scoped. +- ACX Moves the streams (if any) to their previous state before the device was powered down. Stream Instance-scoped. +- WDF Queues are restarted. +- WDF DeviceSelfManagedIoInit. Device-scoped. + - For more information, see [EVT_WDF_DEVICE_SELF_MANAGED_IO_INIT callback function](/windows-hardware/drivers/ddi/wdfdevice/nc-wdfdevice-evt_wdf_device_self_managed_io_init). +- WDF DeviceSelfManagedIoRestart. Device-scoped. + - Init after each power up from Dx. + - For more information, see [EVT_WDF_DEVICE_SELF_MANAGED_IO_RESTART callback function](/windows-hardware/drivers/ddi/wdfdevice/nc-wdfdevice-evt_wdf_device_self_managed_io_restart). + +- ACX StreamAdd (instance) on ACX Circuit (ACX callback on ACX circuits) – invoked at any time after the WDF self-managed I/O Init or Restart has been invoked and device is in D0. Circuit-scoped. + - Input: AcxStreamInit context, ACXCIRCUIT. + - Add callbacks. + - Create an AcxStream (instance). + - Optionally do any post stream Instance init. + - On return, ACX activates this stream instance, and since in this scenario is the only one on the audio path, it allows stream messages to go through. + +## ACX device enumeration and startup for dynamic audio devices + +In this scenario the following are assumed. + +- Dynamic audio support (create/delete audio devices at run-time). +- Device lifetime is not tied to the circuit lifetime. +- A single device can create multiple circuits for different audio devices. +- Piggybacks on the simple static pattern described above by only adding elements specific to dynamic pattern. +- Makes use of child raw PDOs. +- KMDF kernel-mode environment. + +The sequence of start up for this scenario is: + +- WDM DriverEntry. Driver-scoped. + - Init tracing. + - Optionally register for unload. + - Create WDFDRIVER. + - Call ACX to do any post driver init. + - Optionally do any post driver init. + +- WDF DeviceAdd. Device-scoped. + - Call ACX to init the device init context. + - Create device. + - Call ACX to do any post device init. + - Optionally do any post device init. + +- WDF PrepareHardware. Device-scoped. + - Create and init hardware resources (for interrupts and threads, register them with ACX). + +- WDF Device D0 Entry callback. Device-scoped. + +- WDF Queues are restarted. + +- WDF DeviceSelfManagedIoInit. Device-scoped. + +- WDF DeviceSelfManagedIoRestart. Device-scoped. + - Init after each power up from Dx. + +### Circuit dynamic creation (at any time) + +- Driver allocates a [WDFDEVICE_INIT structure](../wdf/wdfdevice_init.md) by calling [WdfPdoInitAllocate](/windows-hardware/drivers/ddi/wdfpdo/nf-wdfpdo-wdfpdoinitallocate). + The driver is responsible for invoking the [WdfDeviceInitFree](/windows-hardware/drivers/ddi/wdfdevice/nf-wdfdevice-wdfdeviceinitfree) if it encounters any failures before successfully creating a device. +- Driver specifies any PnP/power callbacks it wants to receive. +- Driver creates a device. +- Driver instantiates the new device/circuit by calling [AcxDeviceAddCircuitDevice](/windows-hardware/drivers/ddi/acxdevice/nf-acxdevice-acxdeviceaddcircuitdevice). +- WDF/PnP takes over and the simple enum/startup pattern described in the previous section takes place. + +### Circuit dynamic removal + +- Driver invokes [AcxDeviceRemoveCircuitDevice](/windows-hardware/drivers/ddi/acxdevice/nf-acxdevice-acxdeviceremovecircuitdevice) to remove the audio device from the device list. This triggers the power down sequence on the ACX circuit device/circuit entity. The circuit device/circuit is deleted asynchronously. + +- Circuit Providers (AcxFactoryCircuit): + - ACX invokes a driver callback to let the driver know when to create dynamic circuits. + +## ACX device rebalance + +Rebalancing is done when system resource usage requires the operating system to rebalance resources between devices. For general information about rebalance, see [Implement PnP Rebalance for PortCls Audio Drivers](implement-pnp-rebalance-for-portcls-audio-drivers.md). + +ACX supports device rebalance as follows: + +- In the power down WDF/ACX sequence, the driver releases all streaming resources (EvtAcxStreamPowerDown, EvtAcxStreamReleaseHardware), circuit resources (EvtAcxCircuitPowerDown, EvtAcxCircuitReleaseHardware) and device resources (EvtDeviceReleaseHardware). + +- All requests are pended, and handles are left open. + +- In the power up WDF/ACX sequence, the driver makes sure the new resources are compatible with the current ones, and it makes any allowed adjustments to its settings. If the resources are not compatible with the current device/circuit initialization, the driver must delete the current circuits and create new ones. See below more information. + +- In the power up sequence, WDF invokes its EvtDevicePrepareHardware and EvtDeviceD0 entry, and ACX invokes the corresponding EvtAcxCircuitPrepareHardware and EvtAcxCircuitPowerUp, and it moves all streams into its pre-existing states. + +- As soon as the queues move to power up/run state, the I/O flow again. + +ACX doesn't allow remove (fails query-remove) or rebalance (fails query-stop) to take place if there are streams in active (RUN) state. + +Drivers may also opt to always destroy and recreate audio devices on rebalance. This is the same scenario above when the device detects that the new settings are not compatible with the old ones. The deletion of the circuit must be done in EvtDevicePrepareHardware/EvtDeviceReleaseHardware callbacks, and the new circuit is re-created in EvtDevicePrepareHardware. The driver deletes a circuit by un-registering the circuit (using [AcxDeviceRemoveCircuit](/windows-hardware/drivers/ddi//acxdevice/nf-acxdevice-acxdeviceremovecircuit)). + +ACX doesn’t wait for the user mode file handles to be closed before re-creating new circuits. The lifetime of the files system handles is not tied to the lifetime of the hardware resources used by the device/circuits. It is the responsibility of clients to listen for interface arrival/removal and close and re-open file handles. + +Old file handles are marked obsolete and ACX fails all the I/O requests associated with them. + +## See also + +[ACX audio class extensions overview](acx-audio-class-extensions-overview.md) + +[ACX reference documentation](acx-reference.md) + +[PnP and Power Management Callback Sequences](../wdf/pnp-and-power-management-callback-sequences.md) diff --git a/windows-driver-docs-pr/audio/acx-irps.md b/windows-driver-docs-pr/audio/acx-irps.md new file mode 100644 index 0000000000..d1d8c7c23a --- /dev/null +++ b/windows-driver-docs-pr/audio/acx-irps.md @@ -0,0 +1,95 @@ +--- +title: ACX IO request packet IRPs +description: This topic provides a high level summary of the ACX IO request packet IRPs. +ms.date: 04/14/2023 +ms.localizationpriority: medium +--- + +# ACX IO request packet IRPs + +>[!IMPORTANT] +> Some information relates to a prerelease product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here. + +This topic provides a summary of the Audio Class eXtensions (ACX) IO request packet IRPs. + +For general information about the ACX, see [ACX audio class extensions overview](acx-audio-class-extensions-overview.md) and [Summary of ACX Objects](acx-summary-of-objects.md). For information about ACX targets and synchronization, see [ACX targets and driver synchronization](acx-targets.md). + +## IRP request dispatching + +An ACX client specifies an action via a driver request (IRP). For general information about IRPs, see, [I/O request packets](../gettingstarted/i-o-request-packets.md) and [Packet-Driven I/O with Reusable IRPs](../kernel/packet-driven-i-o-with-reusable-irps.md). + +The client sends this request to a circuit/pin/element/stream by using the circuit or stream handle. The request ID is a triplet: + +- set (guid), +- id/index (ulong) +- optional pin-id/node-id (ulong) value. + +At creation time the driver can optionally associates properties/methods/events with one of more of following objects: + +- pin +- circuit +- stream +- element + +Each property/method/event is identified by an ID and a callback handler. By default, ACX defines all the properties/methods/events required by KS-clients (user-mode layers), thus drivers do not need to redefine them. Drivers only need to define their custom properties/methods/events. + +When ACX receives an ACX/KS style IoCtrl request, it validates the request and locks the caller’s buffers in memory. This validation and buffer lock down is done in a WDM pre-process callback that ACX registered at initialization time. During this phase, the ACX adds its own completion callback to the WDM IRP before forwarding it back to WDF for normal dispatching. The completion callback gives ACX an opportunity to add/inject any compatibility workarounds as needed. + +Next WDF invokes the dynamic dispatch IRP callback, in this callback ACX/driver (optionally) associates a WDF queue with the request. In this callback ACX locates the target ACX object: circuit, pin, circuit-element or stream using the handle on which this request was sent, and the optional pin-id/node-id/circuit-element within the request. + +In an audio composite device it is possible that the target object (circuit-only) may be located on a different stack than the one on which the request is originally sent on. In addition, a request may need to act on multiple stacks, an example of this, is a stream change state. + +After the target has been identified, ACX checks if the target circuit/stream-object specifies an override for the default processing queue, if not, ACX uses the default queue associated with current handle. The ACX/driver then instructs WDF to insert the request into the either the specified or the default queue. + +Next WDF invokes the in-caller process callback if present. ACX doesn’t need/use the in-caller process callback because it already locked the buffers in memory in the pre-process callback. Thus, ACX informs WDF to not invoke the in-process callback after specifying the target queue for the request. + +### Secondary queue usage + +The default ACX queue is a power-managed, serial, no-locking queue. The driver should move any request taking an undetermined amount of time into a secondary queue. The driver managed queue could be a manual-passive queue, where the driver can hold on to these requests until it is ready to complete them later. + +### Power reference requests + +ACX automatically power up the device before dispatching a request to the driver. This is done implicitly by using a WDF power managed queues. This creates a behavior similar to portcls. That is, a power reference is taken, before dispatching the request. + +### Invoking the queue’s dispatch handler + +Next WDF takes a power reference and invokes the queue’s dispatch handler. The default queue which is associated with the ACX handler checks for any pre-process overrides, and if present, ACX invokes the registered driver’s pre-process callback. ACX allows the driver to specify overrides based on the type of request (property, event, and method) and (optionally) request IDs. + +If a pre-process callback was specified, after ACX invokes the callback, the request is owned by the driver. The driver may complete the request or forward it back to ACX for normal dispatching. + +If a pre-process callback was not specified, or if the driver gives back the request to ACX, ACX retrieves the target ACX object and locates the declared property/event/method’s callback. It then invokes the callback passing the WDF request and the target ACX Object (circuit/stream/circuit-element). + +Next ACX (or for custom properties, the driver) performs the requested action and completes the request, or if the request takes an undetermined amount of time, the driver can move the request to a secondary queue. The driver is responsible for serializing and completing any active pending requests. + +This diagram illustrates the typical request dispatch workflow. + +![diagram illustrating dispatch workflow showing and audio service, WDF, ACX and a driver](images/audio-acx-dispatch-workflow-1.png) + +This diagram illustrates the dispatch workflow when driver has an ACX preprocess callback defined, although in the end the request is handled by the ACX framework. + +![diagram illustrating dispatch workflow showing and audio service, WDF, ACX and a driver with a preprocess callback](images/audio-acx-dispatch-workflow-2.png) + +### ACX circuit PnP internal interfaces + +To facilitate the communication between ACX Endpoint Manager (EM) and the ACX driver components (kernel-mode or user-mode components), the ACX defines the following internal PnP device interfaces: + +- ACXCATEGORY_CIRCUITFACTORY +- ACXCATEGORY_CIRCUIT + +The EM uses the ACXCATEGORY_CIRCUITFACTORY interface to instruct a target device to create or remove a specific circuit of this type. This interface is active while the underline device is able to create circuits, otherwise it is disabled (example: remove, surprise-removal, stop or manual remove). + +The Audio subsystem uses ACXCATEGORY_CIRCUIT (which may be created on a different device stack than the circuit-manager stack), to track and communicate with the ACX circuit. This interface is active when the circuit has been created and ready to process commands. + +For information about other power and PnP processes, see [ACX device enumeration](acx-device-enumeration.md) and [ACX power management](acx-power-management.md). + +## See also + +[ACX audio class extensions overview](acx-audio-class-extensions-overview.md) + +[ACX reference documentation](acx-reference.md) + +[Summary of ACX Objects](acx-summary-of-objects.md) + +[ACX version information](acx-version-overview.md) + +[ACX multi stack cross driver communications](acx-multi-stack.md) diff --git a/windows-driver-docs-pr/audio/acx-logging-and-debugging.md b/windows-driver-docs-pr/audio/acx-logging-and-debugging.md new file mode 100644 index 0000000000..0bb0003f27 --- /dev/null +++ b/windows-driver-docs-pr/audio/acx-logging-and-debugging.md @@ -0,0 +1,100 @@ +--- +title: ACX logging and debugging +description: This topic provides information on logging, tracing and debugging of the ACX Audio Class Extensions. +ms.date: 04/14/2023 +ms.localizationpriority: medium +--- + +# ACX logging and debugging + +>[!IMPORTANT] +> Some information relates to a prerelease product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here. + +This topic provides information on logging, tracing and debugging of the ACX Audio Class Extensions. + +## ACX Driver Logging + +Software tracing for drivers is usually based on Event Tracing for Windows (ETW), a kernel-level facility that logs trace messages for both kernel-mode and user-mode processes. As ACX drivers are WDF drivers, all of the WDF logging and eventing capabilities are available for ACX driver developers. + +### WPP + +Because ETW can be somewhat complicated to use, most driver developers use the Windows software trace preprocessor (WPP), which simplifies and enhances the process of instrumenting a driver for ETW tracing. + +ACX uses WPP logs for tracing and debugging. For more information, see [Using WPP Software Tracing in KMDF Drivers](../wdf/using-wpp-software-tracing-in-kmdf-drivers.md) and [Adding WPP Software Tracing to a Windows Driver](../devtest/adding-wpp-software-tracing-to-a-windows-driver.md). + +### In-Flight recorder (IFR) + +In-Flight recorder (IFR) is supported and can be viewed via WDFKD, RCDRKD or with the ACXKD debugger extension when it is available. For general information working with IFR logs, see [Using Inflight Trace Recorder (IFR) in KMDF and UMDF 2 Drivers](../devtest/using-wpp-recorder.md) and [Video: Accessing driver IFR logs without a debugger](../wdf/video--accessing-driver-ifr-logs-without-a-debugger.md) + +ACX logs key events using other ETW providers to simplify the visualization of these special events. + +### Adding logging to your driver + +3rd party drivers are highly encouraged to use WPP and ETW events as well. + +This example code, shows checking a return value and logging an appropriate error. + +```cpp + + // + // The driver uses this DDI to delete the circuits from the current device. + // + status = AcxDeviceRemoveCircuit(Device, devCtx->Speaker); + if (!NT_SUCCESS(status)) { DrvLogError(g_AudioDspLog, FLAG_INIT, L"Failed to remove speaker circuit, continuing with ReleaseHardware, %!STATUS!", status); } + status = AcxDeviceRemoveCircuit(Device, devCtx->MicArray); + if (!NT_SUCCESS(status)) { DrvLogError(g_AudioDspLog, FLAG_INIT, L"Failed to remove micarray circuit, continuing with ReleaseHardware, %!STATUS!", status); } + status = AcxDeviceRemoveCircuit(Device, devCtx->SpeakerHp); + if (!NT_SUCCESS(status)) { DrvLogError(g_AudioDspLog, FLAG_INIT, L"Failed to remove speakerHp circuit, continuing with ReleaseHardware, %!STATUS!", status); } + status = AcxDeviceRemoveCircuit(Device, devCtx->MicrophoneHp); + if (!NT_SUCCESS(status)) { DrvLogError(g_AudioDspLog, FLAG_INIT, L"Failed to remove microphoneHp circuit, continuing with ReleaseHardware, %!STATUS!", status); } + status = AcxDeviceRemoveCircuit(Device, devCtx->HDMI); + if (!NT_SUCCESS(status)) { DrvLogError(g_AudioDspLog, FLAG_INIT, L"Failed to remove HDMI circuit, continuing with ReleaseHardware, %!STATUS!", status); } +``` + +The featured version of the Toaster driver sample code provides examples of WMI tracing as well as reusable tracing code. For more information about the Toaster sample, see [Toaster Sample Driver](/samples/microsoft/windows-driver-samples/toaster-sample-driver/). + +### Recommendations for ACX Driver logging + +To improve the reliability of your ACX driver consider the following behaviors for logging. + +- Unexpected return values from stream buffer IO or other regular signal processing activity. +- Unexpected power states or power state transitions. +- Errors related to calls made during updates or re-installation. +- Other behaviors that may lead to “no audio” could be considered for logging. + +### Using the WMI Tracing debugger extensions + +To view trace events in the debugger, use the WMI extension, Wmitrace.dll. It contains a library of functions designed to control and view WMI event tracing. For more information, see [WMI Tracing Extensions (Wmitrace.dll)](../debugger/wmi-tracing-extensions--wmitrace-dll-.md). + +## ACX driver debugging + +ACX drivers are WDF drivers, so the debugging techniques described for WDF drivers, apply to ACX drivers. See the following topics for information on debugging WDF drivers. + +#### General information about the debugging tools + +[Debugging Tools for Windows (WinDbg, KD, CDB, NTSD)](../debugger/index.md) + +#### KMDF debugging + +- [Summary of Debugger Extensions in Wdfkd.dll](../wdf/debugger-extensions-for-kmdf-drivers.md) + +- This walk through uses the traditional Sysvad audio driver, but illustrates some techniques that may be help to ACX drivers. +[Debug Drivers - Step by Step Lab (Sysvad Kernel Mode)](../debugger/debug-universal-drivers--kernel-mode-.md) + +#### Video Walkthroughs + +- [Video: Debugging your driver with WDF source code](../wdf/video--debugging-your-driver-with-wdf-source-code.md) +- [Video Series: Debugging Kernel-Mode Driver Framework Drivers](../wdf/debugging-kernel-mode-driver-framework-drivers.md) + +#### ACX kernel debugger extension library (AcxKd.dll) + +To aid debugging, ACX has a companion kernel debugger extension library (AcxKd.dll). This library aids developers in tracking down issue on single and multi-stack audio paths. The kd extension allows developer to look inside ACX structures. + +>[!NOTE] +> This debugger extension is under development and information will be provided here when it is available. + +## See also + +[ACX audio class extensions overview](acx-audio-class-extensions-overview.md) + +[Summary of ACX objects](acx-summary-of-objects.md) diff --git a/windows-driver-docs-pr/audio/acx-multi-circuit-composition.md b/windows-driver-docs-pr/audio/acx-multi-circuit-composition.md new file mode 100644 index 0000000000..597b1e9baa --- /dev/null +++ b/windows-driver-docs-pr/audio/acx-multi-circuit-composition.md @@ -0,0 +1,230 @@ +--- +title: ACX multi circuit composition +description: This topic provides a summary of multi circuit composition +ms.date: 04/19/2023 +ms.localizationpriority: medium +--- + +# ACX multicircuit composition + +>[!IMPORTANT] +> Some information relates to a prerelease product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here. + +This topic discusses ACX multi circuit composition. For a general overview of ACX and list of ACX terms, see [ACX audio class extensions overview](acx-audio-class-extensions-overview.md). + +As described in [Summary of ACX objects](acx-summary-of-objects.md), an AcxCircuit represents a partial or full audio path to a user perceived audio device (speakers, mic, etc.). An AcxCircuit has at least one input pin and one output pin (ACXPIN), and it may aggregate one or more AcxElements-like objects. + +## ACX circuit identification + +Every ACX circuit has a circuit identifier. ACX defines the following: + +- *Name (str)*, uniquely identifies this circuit audio device type. It is used to locate INF’s setting, and it is part of the symbolic link used to access this circuit from a remote device. Example: “Render0”, “Render1” or “Capture0”. + +- *Symbolic link*. A symbolic link is associated with all the exposed circuits. Clients use this symbolic link to open a communication path with the device/circuit. + +- *Circuit’s component ID (guid)*. Uniquely identifies the circuit instance (vendor specific). It cannot be used in the AcxCircuitTemplate bindings if the Circuit URI was specified. + +- *Circuit’s component URI (str)*. Uniquely identifies the circuit instance (vendor specific). It cannot be used in the AcxCircuitTemplate bindings if the Circuit ID was specified. + +- *Circuit Factory’s component ID (guid)*. Uniquely identifies the circuit factory instance (vendor specific). It cannot be used in the AcxCircuitTemplate bindings if the Circuit Factory URI was specified. + +- *Circuit Factory’s component URI (str)*. Uniquely identifies the circuit factory instance (vendor specific). It cannot be used in the AcxCircuitTemplate bindings if the Circuit Factory ID was specified. + +## ACX circuit composition + +ACX binds circuits together until they form a complete audio path. ACX uses audio bindings to connect audio circuits together. At the same time, each ACX circuit is converted into a KS filter, these KS filters are then detected by the Audio Endpoint Builder (AEB) which runs as user-mode service. AEB scans the detected KS filter graph and creates the software audio endpoint representing the underline audio infrastructure when it detects a complete audio path. + +The following diagram shows the ACX objects used by ACX to detect, build, and monitor the circuits making up the composite audio endpoint. + +![diagram illustrating the acx target architecture showing ACXCIRCUITTEMPLATE, ACXCOMPOSITETEMPLATE (not shown), ACXMANAGER, ACXCIRCUITFACTORY and ACXCIRCUIT. and under that ACXTARGET, ACXSTREAM ACXSTREAMFACTORY with the lowest layer showing ACXTARGETELEMENT and ACXTARGETPIN](images/audio-acx-multi-stack-acx-manager-related-objects.png) + +>[!IMPORTANT] +> Note that only the types shown in blue are public: ACXCIRCUITTEMPLATE, ACXCOMPOSITETEMPLATE (not shown), ACXMANAGER, ACXCIRCUITFACTORY and ACXCIRCUIT. All types shown in violet are internal, and they are listed here only for illustration purposes. The internal types are not guaranteed to stay the same, or be available in different releases of ACX, and must not be called or used directly. + +ACX manager parses the circuit templates at driver init time when the ACX drivers register them with the ACX manager. ACX drivers register composite templates/binding using ACXCIRCUTTEMPLATES (#1). + +When ACX manager receives a circuit template it checks if this is an instance-template or a generic class-template. + +For instance-templates, ACX creates an ACXCOMPOSITEMANAGER (#4), for generic class-templates, ACX creates a ACXCOMPOSITEFACTORY (#2), which is responsible for creating ACXCOMPOSITEMANAGER items (#3) when it detects the ‘core’ circuit of the composite. Core circuits are the circuits that give the identity to a composite audio endpoint. + +The ACXCOMPOSITEMANAGER in turns creates the ACXCOMPOSITE (#5) to represent the underline composite audio endpoint. The composite manager is responsible for monitoring any optional circuit segment that may come up after the composite has been created/initialized. + +The ACXCOMPOSITE in turn creates an ACXCIRCUITMANAGER (#6) for each circuit that is part of the composite. The ACXCIRCUITMANAGER is responsible for creating, monitoring, and controlling a single circuit (#7). + +It may be possible for a circuit to be tagged ‘on-demand’, in such case, the ACXCIRCUITMANAGER finds its circuit factory and request a new circuit for the composite (#8). The ACXCIRCUITFACTORY creates an ACXCIRCUIT as request (#9). + +When all the ACXCIRCUITs are detected and active, the ACXCOMPOSITE becomes active as well and instructs the ACXCIRCUITMANAGERS to turn on the ‘audio’ interfaces for their circuits. + +The following sequence diagram shows how two ACX circuits (Circuit A and B) are bound together to create a full audio path, which is represented by the audio endpoint builder (AEB) with an software audio device. + +![diagram showing columns labeled driver a and driver b, acx interface b, circuit manager and and b and ACX composite and ACX manager with flow arrows shown below showing calling sequence](images/audio-acx-multi-stack-multi-circuit-driver-sequence.png) + +## Multi circuit format negotiation + +This section describes the format negotiation taking places when the audio endpoint is composed by two or more circuits. For general information about ACX Circuits, see [ACX multi stack cross driver communications](acx-multi-stack.md). + +### Downlevel bridge pins + +Downlevel bridge pins are the pins that send data to (render) or receive data from (capture) a physical audio device directly or indirectly. This type of pins may or may not have ACXMODEFORMATLISTs associated with them. These bridge pins have a ‘AcxPinQualifierBridgeB’ or ‘AcxPinQualifierBridgeDevice’ type. For more information about ACXMODEFORMATLIST, see the [acxdataformat.h header](/windows-hardware/drivers/ddi/acxdataformat/). + +![diagram showing the render and capture data flow between a streaming pin, two circuits and a device.](images/audio-acx-multi-stream-flow-sequence.png) + +In this diagram, and article, uplevel and downlevel is used to describe the flow direction, as the direction of the up or down stream flow is dependent on if the pins are sending data to (render) or receiving data (capture). + +### Downlevel bridge pins without ACXMODEFORMATLIST(s) + +A driver may choose not to expose mode-format lists on its downlevel pin. If the mode-format lists are not available on a downlevel bridge pin, a user (via sound-control panel) or other software entity cannot directly control/specify the audio format of this pin and associated streams. These are some scenarios where these lists are not needed: + +- Streaming-only circuits which can be connected to a DSP circuit, to a CODEC circuit, or directly to the audio device. These circuits simply move the data from point A to point B without modifying it. These circuits do not change the data sample rate of the incoming/outgoing stream(s). In this case the mode-format lists are associated with the uplevel pin. + +- Single stream circuits without elements that modify the incoming/outgoing sample rate. An example of this is the USB audio device circuit. In this scenario the mode-format lists are associated with the uplevel pin. + +The absence of the data-format list implies that the stream's data-format originating from this pin is compatible with one of the data-formats of the attached circuit’s uplevel pin. + +#### Downlevel bridge pins with ACXMODEFORMATLIST(s) + +A driver may choose to expose mode-format lists on its downlevel pins. If the mode-format lists are available on a downlevel bridge pin, a user (via sound-control panel) or other software entity can directly control/specify the audio format of this pin and associated streams. + +These are some valid scenarios where these mode-format lists are used: + +- DSP circuits - normally this type of circuits support multiple streams running at different sample rates, these streams are internally converted to a common sample rate and mixed before the data moves to the next circuit. The data-format list controls/specifies the final (for this circuit) sample rate. + +When the data-format list is present, these data-formats need to match data-format samples in the uplevel pin of the next circuit’s pin. Note that modes do not need to match, see the discussion of modes, in the sections below. + +The downlevel format lists, gives the opportunity to user/upper-layer to control the format of the resulting stream, in this case the default value of the list is the sample rate used until an explicit action is taken to change the format on this pin. + +For more information about format lists, see the [acxdataformat.h header](/windows-hardware/drivers/ddi/acxdataformat/). + +### Uplevel bridge pins + +Uplevel bridge pins are the pins that receive data from (render) or send data to (capture) a software module directly or indirectly. This type of pins should have ACXMODEFORMATLISTs associated with them. These bridge pins have a ‘AcxPinQualifierBridgeA’ type. + +The previous diagram shown here again, can also be used to show the render and capture data flow between a streaming pin, two circuits and a device. + +![diagram showing the render and capture data flow between a streaming pin, two circuits and a device.](images/audio-acx-multi-stream-flow-sequence.png) + +#### Uplevel [Bridge] pins without ACXMODEFORMATLIST(s) + +Uplevel pins without mode-format lists are not a valid combination and this results in a misconfigured endpoint. The endpoint is not visible from user point of view. + +#### Uplevel [Bridge] pins with ACXMODEFORMQATLIST(s) + +Uplevel pins must always have one or more ACXMODEFORMATLISTs. The mode-format-lists specify all possible sample rates for a mode and its default sample rate. Different modes may have different sets of sample rates. The default sample rate is the preferred sample rate for that mode. + +### Modes and circuits + +Uplevel pins of single stream circuits or multi-stream circuits can support one or more mode format lists. Single stream circuits have one mode active at one time, while multi-stream circuits can have two or more streams running at the same time possibility using different modes. + +### Mode mapping + +This section gives a brief introduction of the standard modes and explains why ‘mode’ mapping is used. + +**RAW mode:** the stream/circuit doesn’t apply any effects on the stream (except for possibly volume, mute, and safety constraints like speaker protection). + +**DEFAULT mode:** the stream/circuit does some default effect. + +` mode`: the stream/circuit applies effects that are specific to the mode selected. + +It is mandatory for streaming pins to support the raw and/or default mode. It is optional for streaming pins to support any other ` modes`. + +In a composite endpoint, it may be possible for the uplevel circuit to support multiple modes, and for the downlevel circuits to support only RAW and/or DEFAULT. + +Example in a two-circuit endpoint: + +- The uplevel circuit’s downlevel pin supports the modes and associated formats m1{f1,f2} and m2{f3,f4}, i.e., this means that the pin’s stream has a format of f1 or f2 when m1 is used, or a format of f3 or f4 when m2 is used. This assumes that the uplevel circuit is a single stream circuit. + +- The downlevel circuit’s uplevel pin supports default-mode{f1,f2,f3}. + +In this case the mode of the stream is converted from mode to the default mode while keeping the same sample rates. + +*m1/f1 to > default/f1* + +*m1/f2 to > default/f2* + +*m2/f3 to > default/f3* + +Invalid Entry: *m2/f4 to > None* + +The mode mapping is done by the driver with the help of ACX. In the table above, the last entry is invalid, the uplevel circuit’s downlevel pin should remove the *m2/f4* as option for its supported formats. Note that this could have happened in the reverse, i.e., the downlevel circuit’s uplevel pin could have supported also f4 and f5. In which case default-f4 was supported but the default-f5 was not. In such a case it is the downlevel circuit’s uplevel pin responsible to not list m?/f5 as option from its list. Further sections below explain this process. + +#### Format negotiations + +Before ACX enables the audio interfaces of the circuits making up the composite device, it makes sure the circuits can negotiate the mode/formats of the audio data. ACX performs this circuit notification by invoking the composite initialize callback on all the circuits of the composite. The sequence is from downlevel (device side) to uplevel (system side). Circuits have an opportunity to update their formats during this phase. + +#### Device format control panel display + +The current sound control panel logic shows the device format list as follows: + +- If the audio device supports an audio engine element, the list of data-formats displayed in the control panel is the device data-format list, i.e., the data-format list attached to the downlevel pin (which is connected to the audio engine element output pin). +- If the audio device doesn’t support an audio engine element, the list of data-formats displayed in the control panel is the streaming pin data-format list, i.e., the data-format list attacked to the uplevel pin. + +## Multi circuit automatic downlevel stream creation + +ACX uses ACXSTREAMBRIDGE object(s) associated with a downlevel bridge pin to automatically propagate create-stream(s) request to remote circuits. + +When a client app creates a stream, that request is first received by a streaming pin. ACX notifies the driver owing the streaming pin about the create-stream request via the provided callback specified at circuit-creation time. In the callback the driver creates an ACXSTREAM object representing the stream and then it returns the control back to ACX. When ACX receives back the control, it checks if it needs to forward this create-request to the next (downlevel) circuit. Optionally the driver can forward the create-request to the next (downlevel) circuit before returning from its create-stream callback. The latter option allows for the driver to do any post operations after downlevel circuits had the opportunity to process their create-requests. + +ACX uses the following default logic for stream creation: + +- If there is no downlevel bridge pin, all done. +- If the driver has already manually associated the stream with an ACXSTREAMBRIDGE, all done. +- If the downlevel bridge pin doesn’t have an ACXSTREAMBRIDGE for the specified MODE, fail the request. +- ACX adds the new stream the driver created with the retrieved ACXSTREAMBRIDGE. + +The ACXSTREAMBRIDGE acts as a multi-in/single-out. As long as there is an in-stream, ACXSTREAMBRIDGE keeps an out-stream present. The out-stream is deleted only when the last in-stream is removed. ACXSTREAMBRIDGE uses the ACXDATAFORMATLISTs associated with the downlevel bridge pin when deciding the mode and format to be used for the remote circuit. + +ACXSTREAMBRIDGE uses the following logic for selecting the out stream's mode and data-format: + +- If MODE for out-stream is not specified, check if there is a ‘default’ format list. +- If MODE for out-stream is not specified and ‘default’ format list is not present, check if there is a ‘raw’ format list. +- If MODE is NULL_GUID, check if there is a format list associated with the MODE of the first in-stream. +- If MODE is specified, check if there is a format list for this MODE. +- If format list is found, get the default format from the format list. +- If format is not found, ACXSTREAMBRIDGE uses the format of the first in-stream. + +- ACXSTREAMBRIDGE builds a stream create-request using the ACXTARGETSTREAM using the retrieved MODE and data-format as follows: + - If MODE was specified, that MODE is used. + - If MODE was NULL_GUID, the MODE of the first in-stream is used. + - Else no mode is used. + +ACX takes care to delete/close out the target stream when the last in-stream is removed. + +Another job of the ACXSTREAMCIRCUIT is to automatically propagate a stream state along the streaming chain. + +A driver has the opportunity to turn off the default circuit’s remote stream bridge creation by calling [AcxCircuitInitDisableDefaultStreamBridgeHandling](/windows-hardware/drivers/ddi/acxcircuit/nf-acxcircuit-acxcircuitinitdisabledefaultstreambridgehandling) or by manually associating the ACXSTREAM object with a ACXSTREAMBRIDGE before returning control to ACX. In the latter case, the remote stream is created before driver returns from the ‘create-stream’ [EVT_ACX_CIRCUIT_CREATE_STREAM callback function](/windows-hardware/drivers/ddi/acxcircuit/nc-acxcircuit-evt_acx_circuit_create_stream). + +For circuits using multiple capture/render pins, like host/offload/loopback/kws, i.e., when audio-engine element is supported, the driver must create a stream-bridge without any in-mode(s) specified, and manually add the incoming ACXSTREAM objects to the stream-bridge when processing the create-stream callback. + +For more information about stream bridge creation, see: +- [AcxStreamBridgeCreate function](/windows-hardware/drivers/ddi/acxstreams/nf-acxstreams-acxstreambridgecreate) +- [AcxPinAddStreamBridges function](/windows-hardware/drivers/ddi/acxpin/nf-acxpin-acxpinaddstreambridges) +- [AcxStreamBridgeAddStream function](/windows-hardware/drivers/ddi/acxstreams/nf-acxstreams-acxstreambridgeaddstream) + +## Multi circuit automatic stream state propagation to downlevel streams + +ACXSTREAMBRIDGE automatically propagates a stream-state request down-level to remote circuits. When the state of a stream changes, the ACXSTREAMBRIDGE computes the mixed state of the out-stream and sends that new ‘stream-state’ request to the remote stream using the ACXTARGETSTREAM. + +The ACXSTREAM together with the ACXSTREAMBRIDGE use the following logic: + +- Change the uplevel streams’ states first in these scenarios: + - Render && going from Stop->Run + - Capture && going from Run->Stop + - Other && going from Run->Stop + +- Change the uplevel streams’ states last in these scenarios: + - Render && going from Run->Stop + - Capture && going from Stop->Run + - Other && going from Stop->Run + +Drivers have an option to reverse this order via a config setting. + +>[!NOTE] +> It is a requirement for a driver/circuit/stream to always succeed stream transitions from run to stop. On the other hand, it is allowed for a driver to fail the reverse, i.e., from stop to run. + +## See also + +[ACX audio class extensions overview](acx-audio-class-extensions-overview.md) + +[ACX multi stack cross driver communications](acx-multi-stack.md) + +[Summary of ACX Objects](acx-summary-of-objects.md) diff --git a/windows-driver-docs-pr/audio/acx-multi-stack.md b/windows-driver-docs-pr/audio/acx-multi-stack.md new file mode 100644 index 0000000000..a3c1fbd1e8 --- /dev/null +++ b/windows-driver-docs-pr/audio/acx-multi-stack.md @@ -0,0 +1,477 @@ +--- +title: ACX multi stack cross driver communications +description: This topic provides a high level summary of the multi stack cross driver communications. +ms.date: 04/19/2023 +ms.localizationpriority: medium +--- + +# ACX multi stack cross driver communications + +>[!IMPORTANT] +> Some information relates to a prerelease product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here. + +This topic provides a summary of the Audio Class eXtensions (ACX) multi stack cross driver communications. + +For general information about the ACX, see [ACX audio class extensions overview +](acx-audio-class-extensions-overview.md) and [Summary of ACX Objects](acx-summary-of-objects.md). + +For basic information on ACX targets, see [ACX targets and driver synchronization](acx-targets.md) and [ACX IO request packet IRPs](acx-irps.md). + +## Single-Stack audio drivers + +Legacy PortCls and KS audio class drivers only support “single stack” audio drivers. The legacy audio framework communicates and interface with only one miniport driver. It is up to the miniport driver to manage the communication and synchronization with other driver stacks when necessary. + +ACX fully supports single-stack audio drivers. Audio developers can replace their current Portcls and KS miniport driver with an ACX-based driver while keeping the same behavior in relation with other stacks. Although if the audio subsystem uses multi-audio stacks, a better approach would be use to use the multi-stack support in ACX, and let ACX synchronize all these stacks together, as described in the next section of this topic. + +## Multi-Stack audio drivers - componentization + +It is very common for the audio path to go through multiple hardware components handled by different driver stacks to create a complete audio experience. It is typical for a system to have the DSP, CODEC and AMP functionality implemented by different audio technology vendors as shown in the following diagram. + +![diagram illustrating three boxes with arrows to the left of a DSP, CODEC and AMP](images/audio-acx-multi-stack-multiple-hw.png) + +In a multi-stack architecture without a well-defined standard, each vendor is forced to define its own proprietary interface and communications protocol. It is a goal of ACX to facilitate the development of multi-stack audio drivers by taking ownership of the synchronization between these stacks and providing a simple re-usable pattern for drivers communicate with each other. + +Using ACX, the example system DSP, CODEC and AMP hardware design can be supported with the following software architecture. + +![diagram illustrating the acx architecture showing three drivers each with an acx stack for a DSP, CODEC and AMP](images/audio-acx-multi-stack-multiple-hw-three-drivers.png) + +Note that any type of component type instead of the shown DSP, CODEC and AMP, could be used, as ACX does not depend on any specific component type, or specific arrangements of components. + +Third party drivers communicate with each other via ACX with a well-defined protocol. One advantage of this approach is that a single stack could be replaced with another one from a different vendor without requiring changes to the adjacent software stacks. One of the primary goals of the audio class extensions (ACX) framework is to simplify the effort required to develop multi-stack audio drivers assembled from components from different vendors. + +### ACX targets communications example - Circuit + +This example code shows the use of AcxTargetCircuit and [AcxTargetCircuitGetWdfIoTarget](/windows-hardware/drivers/ddi/acxtargets/nf-acxtargets-acxtargetcircuitgetwdfiotarget) to communicate with a remote circuit exposed by a different stack. For more information about ACX Circuits, see [acxcircuit.h](/windows-hardware/drivers/ddi/acxcircuit/). + +This fairly complex aggregator locates circuits and then creates an ioTarget using AcxTargetCircuitGetWdfIoTarget. It then sets custom WDF send options and asynchronously sends the request. Lastly, it checks the status of the send to confirm the request was sent. + +```cpp +NTSTATUS +Aggregator_SendModuleCommand( + _In_ PAGGREGATOR_RENDER_CIRCUIT_CONTEXT CircuitCtx, + _In_ ACX_REQUEST_PARAMETERS Params, + _Out_ ULONG_PTR * OutSize + ) +{ + NTSTATUS status = STATUS_NOT_SUPPORTED; + PKSAUDIOMODULE_PROPERTY moduleProperty = nullptr; + ULONG aggregationDeviceIndex = 0; + PLIST_ENTRY ple; + + *OutSize = 0; + + moduleProperty = CONTAINING_RECORD(Params.Parameters.Property.Control, KSAUDIOMODULE_PROPERTY, ClassId);; + aggregationDeviceIndex = AUDIOMODULE_GET_AGGDEVICEID(moduleProperty->InstanceId); + + ple = CircuitCtx->AggregatorCircuit->AggregatorEndpoint->AudioPaths[aggregationDeviceIndex]->TargetCircuitList.Flink; + while (ple != &CircuitCtx->AggregatorCircuit->AggregatorEndpoint->AudioPaths[aggregationDeviceIndex]->TargetCircuitList) + { + PAUDIO_CIRCUIT circuit = (PAUDIO_CIRCUIT)CONTAINING_RECORD(ple, AUDIO_CIRCUIT, ListEntry); + + if (circuit->Modules) + { + for(ULONG i = 0; i < circuit->Modules->Count; i++) + { + PACX_AUDIOMODULE_DESCRIPTOR descriptor = ((PACX_AUDIOMODULE_DESCRIPTOR)(circuit->Modules + 1) + i); + + // we've identified which aggregation device this call is targeting, + // now locate which circuit implements this module. Within an aggregated device, + // the module class id + instance id must uniquely identify a module. There should + // never be duplicates. + if (IsEqualGUIDAligned(descriptor->ClassId, moduleProperty->ClassId) && + descriptor->InstanceId == moduleProperty->InstanceId) + { + WDFREQUEST request = NULL; + WDF_REQUEST_SEND_OPTIONS sendOptions; + WDF_OBJECT_ATTRIBUTES attributes; + WDFIOTARGET ioTarget; + + // We've now identified which aggregated device this call is targeting. + // The cached module information contains the ID adjusted with the aggregation device + // index. remove the aggregation device index before forwarding the call to the aggregated circuit. + moduleProperty->InstanceId = AUDIOMODULE_GET_INSTANCEID(moduleProperty->InstanceId); + + ioTarget = AcxTargetCircuitGetWdfIoTarget(circuit->AcxTargetCircuit); + + WDF_OBJECT_ATTRIBUTES_INIT(&attributes); + attributes.ParentObject = CircuitCtx->AggregatorCircuit->Circuit; + status = WdfRequestCreate(&attributes, ioTarget, &request); + if (!NT_SUCCESS(status)) + { + goto exit; + } + + status = AcxTargetCircuitFormatRequestForProperty(circuit->AcxTargetCircuit, request, &Params); + if (!NT_SUCCESS(status)) + { + goto exit; + } + + WDF_REQUEST_SEND_OPTIONS_INIT(&sendOptions, WDF_REQUEST_SEND_OPTION_SYNCHRONOUS); + WDF_REQUEST_SEND_OPTIONS_SET_TIMEOUT(&sendOptions, WDF_REL_TIMEOUT_IN_SEC(REQUEST_TIMEOUT_SECONDS)); + + // Whether WdfRequestSend succeeds or fails, we return the status & information, so + // there's no need to inspect the result. + WdfRequestSend(request, ioTarget, &sendOptions); + status = WdfRequestGetStatus(request); + *OutSize = WdfRequestGetInformation(request); + + WdfObjectDelete(request); + goto exit; + } + } + } + + ple = ple->Flink; + } + + status = STATUS_SUCCESS; + +exit: + return status; +} +``` + +### ACX targets communications example - Pin + +This example code shows the use of AcxTargetPin to communicate with a remote circuit’s pin exposed by a different stack. For more information about ACX Pin, see [acxpin.h](/windows-hardware/drivers/ddi/acxpin/). + +It selects the last Volume and Mute elements that are both present in the same circuit in the Endpoint Path. + +```cpp +NTSTATUS FindDownstreamVolumeMute( + _In_ ACXCIRCUIT Circuit, + _In_ ACXTARGETCIRCUIT TargetCircuit +) +{ + NTSTATUS status; + PDSP_CIRCUIT_CONTEXT circuitCtx; + ACX_REQUEST_PARAMETERS params; + WDF_REQUEST_SEND_OPTIONS sendOptions; + WDF_OBJECT_ATTRIBUTES attributes; + WDF_REQUEST_REUSE_PARAMS reuseParams; + + circuitCtx = GetDspCircuitContext(Circuit); + + // + // Note on behavior: This search algorithm will select the last Volume and Mute elements that are both + // present in the same circuit in the Endpoint Path. + // This logic could be updated to select the last Volume and Mute elements, or the first or last + // Volume or the first or last Mute element. + // + + // + // First look through target's pins to determine if there's another circuit downstream. + // If there is, we'll look at that circuit for volume/mute. + // + for (ULONG pinIndex = 0; pinIndex < AcxTargetCircuitGetPinsCount(TargetCircuit); ++pinIndex) + { + ACXTARGETPIN targetPin = AcxTargetCircuitGetTargetPin(TargetCircuit, pinIndex); + ULONG targetPinFlow = 0; + ACX_REQUEST_PARAMETERS_INIT_PROPERTY(¶ms, + KSPROPSETID_Pin, + KSPROPERTY_PIN_DATAFLOW, + AcxPropertyVerbGet, + AcxItemTypePin, + AcxTargetPinGetId(targetPin), + nullptr, 0, + &targetPinFlow, + sizeof(targetPinFlow)); + + RETURN_NTSTATUS_IF_FAILED(SendProperty(targetPin, ¶ms, nullptr)); + + // + // Searching for the downstream pins. For Render, these are the dataflow out pins + // + if (circuitCtx->IsRenderCircuit && targetPinFlow != KSPIN_DATAFLOW_OUT) + { + continue; + } + else if (!circuitCtx->IsRenderCircuit && targetPinFlow != KSPIN_DATAFLOW_IN) + { + continue; + } + + // Get the target pin's physical connection. We'll do this twice: first to get size and allocate, second to get the connection + PKSPIN_PHYSICALCONNECTION pinConnection = nullptr; + auto connection_free = scope_exit([&pinConnection]() + { + if (pinConnection) + { + ExFreePool(pinConnection); + pinConnection = nullptr; + } + }); + + ULONG pinConnectionSize = 0; + ULONG_PTR info = 0; + for (ULONG i = 0; i < 2; ++i) + { + ACX_REQUEST_PARAMETERS_INIT_PROPERTY(¶ms, + KSPROPSETID_Pin, + KSPROPERTY_PIN_PHYSICALCONNECTION, + AcxPropertyVerbGet, + AcxItemTypePin, + AcxTargetPinGetId(targetPin), + nullptr, 0, + pinConnection, + pinConnectionSize); + + status = SendProperty(targetPin, ¶ms, &info); + + if (status == STATUS_BUFFER_OVERFLOW) + { + // Pin connection already allocated, so how did this fail? + RETURN_NTSTATUS_IF_TRUE(pinConnection != nullptr, status); + + pinConnectionSize = (ULONG)info; + pinConnection = (PKSPIN_PHYSICALCONNECTION)ExAllocatePool2(POOL_FLAG_NON_PAGED, pinConnectionSize, DRIVER_TAG); + // RETURN_NTSTATUS_IF_NULL_ALLOC causes compile errors + RETURN_NTSTATUS_IF_TRUE(pinConnection == nullptr, STATUS_INSUFFICIENT_RESOURCES); + } + else if (!NT_SUCCESS(status)) + { + // There are no more connected circuits. Continue with processing this circuit. + break; + } + } + + if (!NT_SUCCESS(status)) + { + // There are no more connected circuits. Continue handling this circuit. + break; + } + + ACXTARGETCIRCUIT nextTargetCircuit; + RETURN_NTSTATUS_IF_FAILED(CreateTargetCircuit(Circuit, pinConnection, pinConnectionSize, &nextTargetCircuit)); + auto circuit_free = scope_exit([&nextTargetCircuit]() + { + if (nextTargetCircuit) + { + WdfObjectDelete(nextTargetCircuit); + nextTargetCircuit = nullptr; + } + }); + + RETURN_NTSTATUS_IF_FAILED_UNLESS_ALLOWED(FindDownstreamVolumeMute(Circuit, nextTargetCircuit), STATUS_NOT_FOUND); + if (circuitCtx->TargetVolumeMuteCircuit == nextTargetCircuit) + { + // The nextTargetCircuit is the owner of the volume/mute target elements. + // We will delete it when the pin is disconnected. + circuit_free.release(); + + // We found volume/mute. Return. + return STATUS_SUCCESS; + } + + // There's only one downstream pin on the current targetcircuit, and we just processed it. + break; + } + + // + // Search the target circuit for a volume or mute element. + // This sample code doesn't support downstream audioengine elements. + // + for (ULONG elementIndex = 0; elementIndex < AcxTargetCircuitGetElementsCount(TargetCircuit); ++elementIndex) + { + ACXTARGETELEMENT targetElement = AcxTargetCircuitGetTargetElement(TargetCircuit, elementIndex); + GUID elementType = AcxTargetElementGetType(targetElement); + + if (IsEqualGUID(elementType, KSNODETYPE_VOLUME) && + circuitCtx->TargetVolumeHandler == nullptr) + { + // Found Volume + circuitCtx->TargetVolumeHandler = targetElement; + } + if (IsEqualGUID(elementType, KSNODETYPE_MUTE) && + circuitCtx->TargetMuteHandler == nullptr) + { + // Found Mute + circuitCtx->TargetMuteHandler = targetElement; + } + } + + if (circuitCtx->TargetVolumeHandler && circuitCtx->TargetMuteHandler) + { + circuitCtx->TargetVolumeMuteCircuit = TargetCircuit; + return STATUS_SUCCESS; + } + + // + // If we only found one of volume or mute, keep searching for both + // + if (circuitCtx->TargetVolumeHandler || circuitCtx->TargetMuteHandler) + { + circuitCtx->TargetMuteHandler = circuitCtx->TargetVolumeHandler = nullptr; + } + + return STATUS_NOT_FOUND; +} +``` + +### ACX targets communications example - Stream + +This example code shows the use of AcxTargetStream to communicate with a remote circuit’s stream. For more information about ACX Streams, see [acxstreams.h](/windows-hardware/drivers/ddi/acxstreams/). + +```cpp + + NTSTATUS status; + PRENDER_DEVICE_CONTEXT devCtx; + WDF_OBJECT_ATTRIBUTES attributes; + ACXSTREAM stream; + STREAM_CONTEXT * streamCtx; + ACXELEMENT elements[2] = {0}; + ACX_ELEMENT_CONFIG elementCfg; + ELEMENT_CONTEXT * elementCtx; + ACX_STREAM_CALLBACKS streamCallbacks; + ACX_RT_STREAM_CALLBACKS rtCallbacks; + CRenderStreamEngine * streamEngine = NULL; + + PAGED_CODE(); + UNREFERENCED_PARAMETER(Pin); + UNREFERENCED_PARAMETER(SignalProcessingMode); + UNREFERENCED_PARAMETER(VarArguments); + + // This unit-test added support for RAW and DEFAULT. + ASSERT(IsEqualGUID(*SignalProcessingMode, AUDIO_SIGNALPROCESSINGMODE_RAW) || + IsEqualGUID(*SignalProcessingMode, AUDIO_SIGNALPROCESSINGMODE_DEFAULT)); + + devCtx = GetRenderDeviceContext(Device); + ASSERT(devCtx != NULL); + + // + // Init streaming callbacks. + // + ACX_STREAM_CALLBACKS_INIT(&streamCallbacks); + streamCallbacks.EvtAcxStreamPrepareHardware = EvtStreamPrepareHardware; + streamCallbacks.EvtAcxStreamReleaseHardware = EvtStreamReleaseHardware; + streamCallbacks.EvtAcxStreamRun = EvtStreamRun; + streamCallbacks.EvtAcxStreamPause = EvtStreamPause; + streamCallbacks.EvtAcxStreamAssignDrmContentId = EvtStreamAssignDrmContentId; + + status = AcxStreamInitAssignAcxStreamCallbacks(StreamInit, &streamCallbacks); + if (!NT_SUCCESS(status)) + { + ASSERT(FALSE); + goto exit; + } + + // + // Init RT streaming callbacks. + // + ACX_RT_STREAM_CALLBACKS_INIT(&rtCallbacks); + rtCallbacks.EvtAcxStreamGetHwLatency = EvtStreamGetHwLatency; + rtCallbacks.EvtAcxStreamAllocateRtPackets = EvtStreamAllocateRtPackets; + rtCallbacks.EvtAcxStreamFreeRtPackets = EvtStreamFreeRtPackets; + rtCallbacks.EvtAcxStreamSetRenderPacket = R_EvtStreamSetRenderPacket; + rtCallbacks.EvtAcxStreamGetCurrentPacket = EvtStreamGetCurrentPacket; + rtCallbacks.EvtAcxStreamGetPresentationPosition = EvtStreamGetPresentationPosition; + + status = AcxStreamInitAssignAcxRtStreamCallbacks(StreamInit, &rtCallbacks); + if (!NT_SUCCESS(status)) + { + ASSERT(FALSE); + goto exit; + } + + // + // Create the stream. + // + WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attributes, STREAM_CONTEXT); + attributes.EvtCleanupCallback = EvtStreamCleanup; + attributes.EvtDestroyCallback = EvtStreamDestroy; + status = AcxRtStreamCreate(Device, Circuit, &attributes, &StreamInit, &stream); + if (!NT_SUCCESS(status)) + { + ASSERT(FALSE); + goto exit; + } + + // START-TESTING: inverted create-stream sequence. + { + ACXSTREAMBRIDGE bridge = NULL; + ACXPIN bridgePin = NULL; + ACXTARGETSTREAM targetStream = NULL; + ACX_STREAM_BRIDGE_CONFIG bridgeCfg; + + ACX_STREAM_BRIDGE_CONFIG_INIT(&bridgeCfg); + bridgeCfg.InModesCount = 0; // no in-modes. this stream-bridge is manually managed. + bridgeCfg.InModes = NULL; + bridgeCfg.OutMode = NULL; // no mode, i.e., default (1st) and raw (2nd). + bridgeCfg.Flags |= AcxStreamBridgeInvertChangeStateSequence; + + WDF_OBJECT_ATTRIBUTES_INIT(&attributes); + attributes.ParentObject = WdfGetDriver(); // bridge is deleted by driver obj in case of error. + + status = AcxStreamBridgeCreate(Circuit, &attributes, &bridgeCfg, &bridge); + if (!NT_SUCCESS(status)) + { + ASSERT(FALSE); + goto exit; + } + + ... + + status = AcxStreamBridgeAddStream(bridge, stream); + if (!NT_SUCCESS(status)) + { + ASSERT(FALSE); + goto exit; + } + + // Get the Target Stream + targetStream = AcxStreamBridgeGetTargetStream(bridge, stream); + if (targetStream == NULL) + { + ASSERT(FALSE); + goto exit; + } +``` + +### ACX targets communications example - Element + +This example code shows the use of AcxTargetElement to communicate with a circuit’s element. For more information about the ACX Targets, see [acxtargets.h](/windows-hardware/drivers/ddi/acxtargets/). + +```cpp + _In_ ACXCIRCUIT Circuit, + _In_ ACXTARGETCIRCUIT TargetCircuit + +... + + // + // Search the target circuit for a volume or mute element. + // This sample code doesn't support downstream audioengine elements. + // + for (ULONG elementIndex = 0; elementIndex < AcxTargetCircuitGetElementsCount(TargetCircuit); ++elementIndex) + { + ACXTARGETELEMENT targetElement = AcxTargetCircuitGetTargetElement(TargetCircuit, elementIndex); + GUID elementType = AcxTargetElementGetType(targetElement); + + if (IsEqualGUID(elementType, KSNODETYPE_VOLUME) && + circuitCtx->TargetVolumeHandler == nullptr) + { + // Found Volume + circuitCtx->TargetVolumeHandler = targetElement; + } + if (IsEqualGUID(elementType, KSNODETYPE_MUTE) && + circuitCtx->TargetMuteHandler == nullptr) + { + // Found Mute + circuitCtx->TargetMuteHandler = targetElement; + } + } +``` + +## See also + +[ACX audio class extensions overview](acx-audio-class-extensions-overview.md) + +[Summary of ACX Objects](acx-summary-of-objects.md) + +[ACX reference documentation](acx-reference.md) + +[ACX IO request packet IRPs](acx-irps.md) + +[ACX targets and driver synchronization](acx-targets.md) + +[ACX reference documentation](acx-reference.md) \ No newline at end of file diff --git a/windows-driver-docs-pr/audio/acx-power-management.md b/windows-driver-docs-pr/audio/acx-power-management.md new file mode 100644 index 0000000000..df0c81267c --- /dev/null +++ b/windows-driver-docs-pr/audio/acx-power-management.md @@ -0,0 +1,127 @@ +--- +title: ACX power management +description: This topic provides a summary of the ACX power management +ms.date: 04/19/2023 +ms.localizationpriority: medium +--- + +# ACX power management + +>[!IMPORTANT] +> Some information relates to a prerelease product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here. + +This topic discusses ACX power management. For information about ACX device enumeration, startup and shutdown, and device rebalance, see [ACX device enumeration](acx-device-enumeration.md). For a general overview of ACX, see [ACX audio class extensions overview](acx-audio-class-extensions-overview.md). + +ACX leverages the WDF KMDF PnP power behavior. For more information about KMDF power management sequences, see [PnP and Power Management Callback Sequences](../wdf/pnp-and-power-management-callback-sequences.md). + +## ACX device enumeration and startup for static audio devices + +To learn about how ACX startup works, the following scenario will be described. + +## ACX device surprise removal + +The WDF framework can call the [EvtDeviceSurpriseRemoval](/windows-hardware/drivers/ddi/wdfdevice/nc-wdfdevice-evt_wdf_device_surprise_removal) at any time, i.e., this callback is not serialized with the power down sequence. The WDF driver should not take any action on receiving this callback except for taking note that the device was surprise removed. + +The power down surprise removal callback sequence is identical to the power down Dx and remove cases, WDF doesn’t invoke the following callbacks on the surprise removal path: + +- EvtDeviceArmWakeFrom* +- EvtIoStop (purge power-managed queues's) +- EvtDeviceSelfManagedIoFlush (flush I/O buffers) + +For more information, see [PnP and Power Management Callback Sequences](../wdf/pnp-and-power-management-callback-sequences.md). + +## ACX circuit power-up and startup + +A "dynamic" AcxCircuit can be added at any time. The driver creates a new child PDO device and associates the new AcxCircuit when handling the WDF PrepareHardware callback for this PDO device. The lifetime of a "dynamic' circuit is not bound to the lifetime of the FDO. + +A "static" AcxCircuit can only be added when the driver is handling the WDF PrepareHardware callback for its FDO device. The lifetime of a "static" circuit is bound to the lifetime of the FDO. + +An ACX driver can also create AcxFactoryCircuit objects (circuit providers) during power up sequence. An AcxFactoryCircuit object uses dynamic circuit creation for adding ACXCIRCUITS when requested by ACX. This feature is very useful when building composite endpoints, i.e., audio endpoint made up of two or more ACXCIRCUITs linked together. + +The ACX Circuit defines the following callbacks which are invoked during the AcxCircuit / Audio Endpoint initialization: + +[EvtAcxCircuitPrepareHardware](/windows-hardware/drivers/ddi/acxcircuit/nc-acxcircuit-evt_acx_circuit_prepare_hardware): ACX invokes this callback just after WDF delivers its WDF prepare hardware callback. It gives an opportunity to the driver to do any 'prepare-hardware' specific to the circuit. This call is serialized by ACX. Device is not in D0 when this call is invoked. + +[EvtAcxCircuitPowerUp](/windows-hardware/drivers/ddi/acxcircuit/nc-acxcircuit-evt_acx_circuit_power_up): ACX invokes this callback just after coming back from Dx. This call is serialized by ACX. Device is in D0. + +For composite endpoints AcxCircuits can optionally register for these callbacks: +[EvtAcxCircuitCompositeCircuitInitialize](/windows-hardware/drivers/ddi/acxcircuit/nc-acxcircuit-evt_acx_circuit_composite_circuit_initialize), invoked the first time ACX detects that this ACXCIRCUIT is visible, i.e., the associated device went in D0 and made this circuit visible to entities external to its own stack. The circuit's audio interfaces are still in the OFF state. + +[EvtAcxCircuitCompositeInitialize](/windows-hardware/drivers/ddi/acxcircuit/nc-acxcircuit-evt_acx_circuit_composite_initialize), invoked each time ACX is finishing up the init of a composite endpoint. After this callback ACX turns on the audio interfaces of this circuit. + +[EvtAcxCircuitCompositeDeinitialize](/windows-hardware/drivers/ddi/acxcircuit/nc-acxcircuit-evt_acx_circuit_composite_deinitialize), invoked each time ACX is tearing down a composite endpoint. Drivers may not receive this callback if its own stack has been surprise-removed, or unable to process I/O. + +If present, stream instances are restored to their pre-power down states. + +## ACX circuit power-down and removal + +A "dynamic" AcxCircuit can be removed at any time by invalidating and removing the device object associated with the circuit. The associated circuit can be removed / detached from the removed device when the driver handles the WDF PrepareHardware/ReleaseHardware callbacks for this PDO device. The lifetime of a "dynamic" circuit is not bound to the lifetime of the FDO. + +A "static" AcxCircuit can only be removed when the driver is handling the WDF PrepareHardware/ReleaseHardware callbacks for its FDO device. The lifetime of a "static" circuit is bound to the lifetime of the FDO. + +The driver can remove an AcxFactoryCircuit (circuit provider) in its the WDF PrepareHardware/ReleaseHardware callbacks. Removing an AcxFactoryCircuit has the effect of removing all its associated "dynamic" AcxCircuit(s). AcxCircuit(s) can also be removed when the ACX manager tells a circuit factory to remove a specific circuit, or when the ACX manager closes its AcxFactoryCircuit handles - in this scenario ACX closes all the circuits associated with that handle. + +The [ACX_CIRCUIT_PNPPOWER_CALLBACKS structure](/windows-hardware/drivers/ddi/acxcircuit/ns-acxcircuit-acx_circuit_pnppower_callbacks) describes the following callbacks that can be used by an ACX driver. + +[EvtAcxCircuitPowerDown](/windows-hardware/drivers/ddi/acxcircuit/nc-acxcircuit-evt_acx_circuit_power_down): ACX invokes this callback just before going in Sx/Dx/Stop/Removal/SurpriseRemoval and when the driver removes the circuit. This call is serialized by ACX. Device is in D0, although keep in mind that the device could be Surprise Removed at any time (which means the associated hardware is gone). + +[EvtAcxCircuitReleaseHardware](/windows-hardware/drivers/ddi/acxcircuit/nc-acxcircuit-evt_acx_circuit_release_hardware): ACX invokes this callback just before WDF delivers its WDF release hardware callback. It gives an opportunity to the driver to do any cleanup while the circuit is still alive. This call is serialized by ACX. Device is not in D0 when this call is invoked. + +[EvtWdfObjectContextCleanup](/windows-hardware/drivers/ddi/wdfobject/nc-wdfobject-evt_wdf_object_context_cleanup): WDF invokes this callback when the WDF/ACX object is deleted. This call is synchronous with the deletion of the WDF object call. Device may not be in D0 when this call is invoked. The callback is running at Passive level. + +[EvtWdfObjectContextDestory](/windows-hardware/drivers/ddi/wdfobject/nc-wdfobject-evt_wdf_object_context_destroy): WDF invokes this callback after the last ref on this object goes away. This call is asynchronous with the deletion of the WDF object call. Device may not be in D0 when this call is invoked. This callback is invoked only after the last reference on the object goes away. The callback is running at <= DPC level. The exact IRQL depends on the IRQL of the thread releasing the last ref. + +## ACX device idle management + +ACX leverages the WDF idle management infrastructure. ACX drivers uses the following WDF DDIs to enable idle management: + +[WdfDeviceAssignS0IdleSettings](/windows-hardware/drivers/ddi/wdfdevice/nf-wdfdevice-wdfdeviceassigns0idlesettings): this call specifies the type of idle timeout and idle management. The ACX driver is free to use the appropriate setting for its device. + +[WdfDeviceStopIdle](/windows-hardware/drivers/ddi/wdfdevice/nf-wdfdevice-wdfdevicestopidle): this call prevents the device from idling. Note that his call doesn’t block Sx requests. That is, the device goes in Dx independently of the number of active power references when the system goes to a lower power state. + +[WdfDeviceResumeIdle](/windows-hardware/drivers/ddi//wdfdevice/nf-wdfdevice-wdfdeviceresumeidle): this call allows the device to restart its idle timeout. + +In a multi-stack/circuit scenario, different stacks may have different idle timeouts. This is because of the different power settings/requirements of each stack, so different idle timeouts are appropriate. + +### Power management framework (PoFx) and driver-managed idle timeout + +Note that WDF does not directly support Fx device/component states. To use these states, the driver must use driver-managed idle timeout. For more information about the use of Fx device component states and driver-managed idle timeout, see the following topics. + +- [Component-Level Power Management](../kernel/component-level-power-management.md) +- [Supporting Multiple-Component Devices with Single or Multiple Functional Power State](../wdf/supporting-multiple-functional-power-states-for-multiple-component-devices.md) + +Windows provides a run-time power management framework (PoFx) which adds support for component-level power management. A component, or subdevice, is a functional hardware unit in a device that can be turned on or switched to a low-power state independently of the other components in the same device. For more information, see [Overview of the Power Management Framework](../kernel/overview-of-the-power-management-framework.md). + +### ACX driver and power managed queues + +WDF supports power-managed I/O queues. This type of queue is fully integrated with WDF power management. WDF invokes the queue’s callbacks at various steps in the power up/power down WDF sequence. For more information, see [Using Power-Managed I/O Queues](../wdf/using-power-managed-i-o-queues.md). + +ACX Drivers can use this type of queue only if the driver is not using single/multi-component with multi-state (Fx) feature. + +## ACX driver and D3Hot / D3Cold (D3) states + +Audio drivers know when to go in D3Hot or D3Cold based on the information available in the [ACX_DX_EXIT_LATENCY enumeration](/windows-hardware/drivers/ddi/acxdevice/ne-acxdevice-acx_dx_exit_latency). + +```cpp +typedef enum _ACX_DX_EXIT_LATENCY { + AcxDxExitLatencyInstant = 0, + AcxDxExitLatencyFast, + AcxDxExitLatencyResponsive +} ACX_DX_EXIT_LATENCY; +``` + +**AcxDxExitLatencyFast** corresponds to D3Hot (DSP on) and **AcxDxExitLatencyResponsive** corresponds to D3Cold (DSP off). + +Audio drivers can get the ACX_DX_EXIT_LATENCY value by calling the [AcxDeviceGetCurrentDxExitLatency function](/windows-hardware/drivers/ddi/acxdevice/nf-acxdevice-acxdevicegetcurrentdxexitlatency). + +WDF knows about the D3Cold capabilities of the driver via the WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS’s ExcludeD3Cold field. The driver passes this struct as input to the WdfDeviceAssignS0IdleSettings. WDF Drivers can invoke the WdfDeviceAssignS0IdleSettings multiple times to turn on or off D3Cold depending on the system environment, i.e., in response to ACX. For more information, see [WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS structure](/windows-hardware/drivers/ddi/wdfdevice/ns-wdfdevice-_wdf_device_power_policy_idle_settings). + +## See also + +[ACX device enumeration](acx-device-enumeration.md) + +[ACX reference documentation](acx-reference.md) + +[ACX audio class extensions overview](acx-audio-class-extensions-overview.md) + +[PnP and Power Management Callback Sequences](../wdf/pnp-and-power-management-callback-sequences.md) diff --git a/windows-driver-docs-pr/audio/acx-reference.md b/windows-driver-docs-pr/audio/acx-reference.md new file mode 100644 index 0000000000..8a4b891d94 --- /dev/null +++ b/windows-driver-docs-pr/audio/acx-reference.md @@ -0,0 +1,72 @@ +--- +title: ACX reference documentation +description: This topic provides a high level overview of the ACX reference documentation. +ms.date: 04/19/2023 +ms.localizationpriority: medium +--- + +# ACX reference documentation + +>[!IMPORTANT] +> Some information relates to a prerelease product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here. + +This topic describes the header level reference documentation for the ACX audio class extensions. + +For a general overview of ACX, see [ACX audio class extensions overview](acx-audio-class-extensions-overview.md). ACX is based on the Windows Driver Framework (WDF) and WDF reference topics can also be useful when looking at the functions and callbacks in ACX. For more information about WDF see [Introduction to Framework Objects](../wdf/introduction-to-framework-objects.md). + +The following ACX headers have reference documentation available. + +Just like WDF drivers, DEVICE and DRIVER are used to initialize the base driver. + +- [acxdevice.h](/windows-hardware/drivers/ddi/acxdevice/) +- [acxdriver.h](/windows-hardware/drivers/ddi/acxdriver/) + +Pins, streams and circuits are used to route audio signals. + +- [acxpin.h](/windows-hardware/drivers/ddi/acxpin/) +- [acxstreams.h](/windows-hardware/drivers/ddi/acxstreams/) +- [acxcircuit.h](/windows-hardware/drivers/ddi/acxcircuit/) +- [acxtargets.h](/windows-hardware/drivers/ddi/acxtargets/) + +The data formats are controlled using this header. + +- [acxdataformat.h](/windows-hardware/drivers/ddi/acxdataformat/) + +The acxelements header provides access to specific audio system elements, such as volume, mute, peakmeter and the keyword spotter. + +- [acxelements.h](/windows-hardware/drivers/ddi/acxelements/) + +Events and requests allow for notification. + +- [acxevents.h](/windows-hardware/drivers/ddi/acxevents/) +- [acxrequest.h](/windows-hardware/drivers/ddi/acxrequest/) + +An object bag, which can be used to store and retrieve configuration information and is defined in acxmisc. + +- [acxmisc.h](/windows-hardware/drivers/ddi/acxmisc/) + +The ACX manager is used for supporting composite audio endpoints. + +- [acxmanager.h](/windows-hardware/drivers/ddi/acxmanager/) + +## See also + +[ACX audio class extensions overview](acx-audio-class-extensions-overview.md) + +[Summary of ACX objects](acx-summary-of-objects.md) + +[ACX version information](acx-version-overview.md) + +[ACX logging and debugging](acx-logging-and-debugging.md) + +[ACX targets and driver synchronization](acx-targets.md) + +[ACX IO request packet IRPs](acx-irps.md) + +[ACX device enumeration](acx-device-enumeration.md) + +[ACX power management](acx-power-management.md) + +[ACX multi stack cross driver communications](acx-multi-stack.md) + +[ACX streaming](acx-streaming.md) diff --git a/windows-driver-docs-pr/audio/acx-streaming.md b/windows-driver-docs-pr/audio/acx-streaming.md new file mode 100644 index 0000000000..ce6310103e --- /dev/null +++ b/windows-driver-docs-pr/audio/acx-streaming.md @@ -0,0 +1,552 @@ +--- +title: ACX streaming +description: This topic provides a summary of the ACX streaming and the associated buffering, which is critical to a glitch free audio experience. +ms.date: 05/26/2023 +ms.localizationpriority: medium +--- + +# ACX streaming + +>[!IMPORTANT] +> Some information relates to a prerelease product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here. + +This topic discusses ACX streaming and the associated buffering, which is critical to a glitch free audio experience. It describes the the mechanisms used by the driver to communicate about the stream state and manage the buffer for the stream. For a list of common ACX audio terms and an introduction to ACX, see [ACX audio class extensions overview](acx-audio-class-extensions-overview.md). + +## ACX streaming types + +An AcxStream represents an audio stream on a specific circuit’s hardware. An AcxStream may aggregate one or more AcxElements-like objects. + +The ACX framework supports two stream types. The first stream type, the *RT Packet Stream*, provides support for allocating RT packets and using RT packets for transferring audio data to or from the device hardware along with stream state transitions. The second stream type, the *Basic Stream*, provides only support for stream state transitions. + +In a single circuit endpoint the circuit must be a streaming circuit that creates an RT Packet Stream. If two or more circuits are connected to create an endpoint, the first circuit in the endpoint is the streaming circuit and creates an RT Packet Stream; connected circuits will create Basic Streams to receive events related to stream state transitions. + +For more information, see *ACX Stream* in [Summary of ACX Objects](acx-summary-of-objects.md). The DDIs for stream are defined in the [acxstreams.h](/windows-hardware/drivers/ddi/acxstreams) header. + +## ACX streaming communications stack + +There are two types of communications for ACX Streaming. One communications path is used for controlling the streaming behavior, for commands such as Start, Create, and Allocate, that will use the standard ACX communications. The ACX framework uses IO Queues and passes along WDF Requests using the queues. The queue behavior is hidden from the actual driver code through the use of Evt callbacks and ACX functions, though the driver is also be given a chance to pre-process all WDF Requests. + +The second and more interesting communications path, is used for the audio streaming signaling. This involves telling the driver when a packet is ready and receiving data on when the driver has finished processing a packet.  + +The main requirements for streaming signaling:  + +- Support Glitch-Free Playback  + - Low Latency  + - Any necessary locks are limited to the stream in question +- Ease of use for driver developer  + +To communicate with the driver to signal streaming state, ACX uses events with a shared buffer and direct IRP calls. These are described next. + +### Shared buffer + +For communicating from the driver to the client, a shared buffer and event are used. This ensures the client does not need to wait or poll, and that the client can determine everything it needs to continue streaming while reducing or eliminating the need for direct IRP calls. + +The device driver uses a shared buffer to communicate to the client which packet is being rendered from or captured to. This shared buffer includes the packet count (1-based) of the last completed packet along with the QPC (QueryPerformanceCounter) value of the completion time. For the device driver, it must indicate this information by calling [AcxRtStreamNotifyPacketComplete](/windows-hardware/drivers/ddi/acxstreams/nf-acxstreams-acxrtstreamnotifypacketcomplete). When the device driver calls AcxRtStreamNotifyPacketComplete, the ACX framework will update the shared buffer with the new packet count and QPC and signal an event shared with the client to indicate that the client may read the new packet count. + +#### Direct IRP calls + +For communicating from the client to the driver, direct IRP calls are used. This reduces the complexities around ensuring WDF requests are handled in a timely manner and has been proven to work well in the existing architecture. + +The client may at any time request the current packet count or indicate the current packet count to the device driver. These requests will call the [EvtAcxStreamGetCurrentPacket](/windows-hardware/drivers/ddi/acxstreams/nc-acxstreams-evt_acx_stream_get_current_packet) and [EvtAcxStreamSetRenderPacket](/windows-hardware/drivers/ddi/acxstreams/nc-acxstreams-evt_acx_stream_set_render_packet) device driver event handlers. The client may also request the current capture packet which will call the [EvtAcxStreamGetCapturePacket](/windows-hardware/drivers/ddi/acxstreams/nc-acxstreams-evt_acx_stream_get_capture_packet) device driver event handler. + +#### Similarities with PortCls + +The combination of direct IRP calls and shared buffer used by ACX is similar to how buffer completion handling is communicated in PortCls. The IRPs are very similar and the shared buffer introduces the ability for the driver to directly communicate packet count and timing without relying on IRPs. +  +Drivers will need to ensure they do nothing that requires access to locks that are also used in the stream control paths – this is necessary to prevent glitching.  + +## Large buffer support for low power playback  + +To reduce the amount of power consumed when playing back media content, it is important to reduce the amount of time the APU spends in a high-power state. Since the normal audio playback uses 10ms buffers, the APU always needs to be active. To give the APU the time it needs to reduce state, ACX drivers are allowed to advertise support for significantly larger buffers, in the 1-2 second size range. This means the APU can wake up once every 1-2 seconds, do the operations required at maximum speed to prepare the next 1-2 second buffer, and then go to the lowest possible power state until the next buffer is needed.  + +In existing streaming models low power playback is supported through Offload Playback. An audio driver advertises support for Offload Playback by exposing an AudioEngine node on the wave filter for an endpoint. The AudioEngine node provides a means to control the DSP engine the driver uses to render the audio from the large buffers with the desired processing. + +The AudioEngine node provides these facilities:  + +- Audio Engine Description, which tells the audio stack which pins on the wave filter provide offload and loopback support (and host playback support).  +- Buffer Size Range, which tells the audio stack the minimum and maximum buffer sizes that can be supported for offload. playback. The Buffer Size Range can change dynamically based on system activity.  +- Format support, including supported formats, the current device mix format, and the device format.  +- Volume, including ramping support, since with the larger buffers software volume will not be responsive. +- Loopback Protection, which tells the driver to mute the AudioEngine Loopback pin if one or more of the Offloaded streams contains protected content.  +- Global FX state, to enable or disable GFX on the AudioEngine.  + +When a stream is created on the Offload Pin, the stream supports Volume, Local FX, and Loopback Protection.  + +### Low power playback with ACX + +The ACX framework uses the same model for low power playback. The driver creates three separate ACXPIN objects for host, offload, and loopback streaming, along with an ACXAUDIOENGINE element that describes which of these pins are used for host, offload, and loopback. The driver adds the pins and ACXAUDIOENGINE element to the ACXCIRCUIT during circuit creation. + +### Offloaded stream creation + +The driver will also add an ACXAUDIOENGINE element to streams created for offload to allow control over volume, mute, and peak meter. + +### Streaming diagram + +This diagram shows a multi-stack ACX driver. + +![diagram illustrating three boxes with a DSP, CODEC and AMP and a kernel streaming interface shown on top](images/audio-acx-multi-stack-kernel-streaming.png) + +Each ACX driver controls a separate portion of the audio hardware and could be provided by a different vendor. ACX provides a compatible kernel streaming interface to allow applications to run as is. + +#### Stream pins  + +Each ACXCIRCUIT has at least one Sink Pin and one Source Pin. These Pins are used by the ACX framework to expose the circuit’s connections to the audio stack. For a Render circuit, the Source Pin is used to control the render behavior of any stream created from the circuit. For a Capture circuit, the Sink Pin is used to control the capture behavior of any stream created from the circuit. +  +ACXPIN is the object used to control streaming in the Audio Path. The streaming ACXCIRCUIT is responsible for creating the appropriate ACXPIN object(s) for the Endpoint Audio Path at circuit creation time and registering the ACXPINs with ACX. The ACXCIRCUIT only needs to create the render or capture pin or pins for the Circuit; the ACX framework will create the other pin needed to connect to and communicate with the circuit.  +  +#### Streaming circuit + +When an endpoint is composed of a single circuit, that circuit is the streaming circuit. + +When an endpoint is composed of more than one circuit created by one or more device drivers, the circuits are connected in the specific order determined by the ACXCOMPOSITETEMPLATE that describes the composed endpoint. The first circuit in the endpoint is the streaming circuit for the endpoint. + +The streaming circuit should use [AcxRtStreamCreate](/windows-hardware/drivers/ddi/acxstreams/nf-acxstreams-acxrtstreamcreate) to create an RT Packet Stream in response to [EvtAcxCircuitCreateStream](/windows-hardware/drivers/ddi/acxcircuit/nc-acxcircuit-evt_acx_circuit_create_stream). The ACXSTREAM created with AcxRtStreamCreate will allow the streaming circuit driver to allocate the buffer used for streaming and to control the streaming flow in response to the client and hardware needs. + +Following circuits in the endpoint should use [AcxStreamCreate](/windows-hardware/drivers/ddi/acxstreams/nf-acxstreams-acxstreamcreate) to create a Basic Stream in response to EvtAcxCircuitCreateStream. The ACXSTREAM objects created with AcxStreamCreate by the following circuits will allow the drivers to configure hardware in response to stream state changes such as Pause or Run. + +The streaming ACXCIRCUIT is the first circuit to receive the requests to create a stream. The request includes the device, the pin, and the data format (including mode). + +Each ACXCIRCUIT in the Audio Path will create an ACXSTREAM object that represents the circuit’s stream instance. The ACX framework links the ACXSTREAM objects together (in much the same way the ACXCIRCUIT objects are linked).  + +#### Upstream and downstream circuits + +Stream creation starts at the streaming circuit and is forwarded to each downstream circuit in the order the circuits are connected. The connections are made between bridge pins created with Communication equal to AcxPinCommunicationNone. The ACX framework will create one or more bridge pins for a circuit if the driver doesn't add them at circuit creation time. + +For each circuit starting with the streaming circuit, the AcxPinTypeSource bridge pin will connect to the next downstream circuit. The final circuit will have an endpoint pin describing the audio endpoint hardware (such as whether the endpoint is a Microphone or Speaker and whether the Jack is plugged in). + +For each circuit following the streaming circuit, the AcxPinTypeSink bridge pin will connect to the next upstream circuit. + +#### Stream format negotiation  + +The driver advertises the supported formats for stream creation by adding the supported formats per mode to the ACXPIN used for stream creation with [AcxPinAssignModeDataFormatList](/windows-hardware/drivers/ddi/acxpin/nf-acxpin-acxpinassignmodedataformatlist) and [AcxPinGetRawDataFormatList](/windows-hardware/drivers/ddi/acxpin/nf-acxpin-acxpingetrawdataformatlist). For multi circuit endpoints, an ACXSTREAMBRIDGE can be used to coordinate mode and format support between ACX Circuits. The supported stream formats for the endpoint are determined by the streaming ACXPINs created by the streaming circuit. The formats used by the following circuits are determined by the bridge pin of the previous circuit in the endpoint. + +By default, the ACX framework will create an ACXSTREAMBRIDGE between each circuit in a multi circuit endpoint. The default ACXSTREAMBRIDGE will use the RAW mode's default format of the bridge pin of the upstream circuit when forwarding the stream creation request to the downstream circuit. If the upstream circuit's bridge pin has no formats, the original stream format will be used. If the connected pin of the downstream circuit does not support the format being used, stream creation will fail. + +If a device circuit is performing a stream format change, the device driver should add the downstream format to the downstream bridge pin. +  +#### Stream creation  + +The first step in Stream Creation is creating the ACXSTREAM instance for each ACXCIRCUIT in the Endpoint Audio Path. ACX will call each circuit’s [EvtAcxCircuitCreateStream](/windows-hardware/drivers/ddi/acxcircuit/nc-acxcircuit-evt_acx_circuit_create_stream). ACX will start with the head circuit and call each circuit’s EvtAcxCircuitCreateStream in order, ending with the tail circuit. The order can be reversed by specifying the AcxStreamBridgeInvertChangeStateSequence flag (defined in [ACX_STREAM_BRIDGE_CONFIG_FLAGS](/windows-hardware/drivers/ddi/acxstreams/ne-acxstreams-acx_stream_bridge_config_flags)) for the Stream Bridge. After all circuits have created a stream object, the stream objects will handle streaming logic. + +The Stream Creation Request is sent to the appropriate PIN generated as part of the head circuit’s topology generation by calling the EvtAcxCircuitCreateStream specified during head circuit creation.  + +The streaming circuit is the upstream circuit that initially handles the stream creation request. + +- It updates the ACXSTREAM_INIT structure, assigning AcxStreamCallbacks and AcxRtStreamCallbacks +- It creates the ACXSTREAM object using AcxRtStreamCreate +- It creates any stream-specific elements (e.g. ACXVOLUME or ACXAUDIOENGINE)  +- It adds the elements to the ACXSTREAM object  +- It returns the ACXSTREAM object that was created to the ACX framework + +ACX then forwards the stream creation to the next downstream circuit. + +- It updates the ACXSTREAM_INIT structure, assigning AcxStreamCallbacks +- It creates the ACXSTREAM object using AcxStreamCreate +- It creates any stream-specific elements +- It adds the elements to the ACXSTREAM object +- It returns the ACXSTREAM object that was created to the ACX framework + +The communication channel between circuits in an audio path uses ACXTARGETSTREAM objects. In this example, each circuit will have access to an IO Queue for the circuit in front of it and the circuit behind it in the Endpoint Audio Path. In addition, an Endpoint Audio Path is linear and bi-directional. The actual IO Queue handling is performed by the ACX framework.  +  +While creating the ACXSTREAM object, each circuit can add Context information to the ACXSTREAM object to store and track private data for the stream. + +#### Render stream example + +Creating a render stream on an Endpoint Audio Path composed of three circuits: DSP, CODEC, and AMP. The DSP circuit functions as the streaming circuit, and has provided an EvtAcxPinCreateStream handler. The DSP circuit also functions as a filter circuit: depending on the stream mode and configuration, it may apply signal processing to the audio data. The CODEC circuit represents the DAC, providing the audio sink functionality. The AMP circuit represents the analog hardware between the DAC and the speaker. The AMP circuit might handle jack detection or other endpoint hardware details. + +1. AudioKSE calls NtCreateFile to create a stream. +2. This filters through ACX and ends with calling the DSP circuit’s EvtAcxPinCreateStream with the pin, dataformat (including mode), and device information.  +3. The DSP circuit validates the dataformat information to ensure it can handle the created stream.  +4. The DSP circuit creates the ACXSTREAM object to represent the stream.  +5. The DSP circuit allocates a private context structure and associates it with the ACXSTREAM.  +6. The DSP circuit returns flow of execution to the ACX framework, which then calls into the next circuit in the Endpoint Audio Path, the CODEC circuit.  +7. The CODEC circuit validates the dataformat information to confirm it can handle rendering the data.  +8. The CODEC circuit allocates a private context structure and associates it with the ACXSTREAM.  +9. The CODEC circuit adds itself as a stream sink to the ACXSTREAM. +10. The CODEC circuit returns flow of execution to the ACX framework, which then calls into the next circuit in the Endpoint Audio Path, the AMP circuit.  +11. The AMP circuit allocates a private context structure and associates it with the ACXSTREAM.  +12. The AMP circuit returns flow of execution to the ACX framework. At this point, stream creation is complete.  + +#### Large buffer streams  + +Large buffer streams are created on the ACXPIN designated for Offload by the ACXCIRCUIT’s ACXAUDIOENGINE element. + +To support offload streams, the device driver should do the following during the streaming circuit creation: + +1. Create the Host, Offload, and Loopback ACXPIN objects and add them to the ACXCIRCUIT. +2. Create ACXVOLUME, ACXMUTE, and ACXPEAKMETER elements. These will not be added directly to the ACXCIRCUIT. +3. Initialize an [ACX_AUDIOENGINE_CONFIG structure](/windows-hardware/drivers/ddi/acxelements/ns-acxelements-acx_audioengine_config), assigning the HostPin, OffloadPin, LoopbackPin, VolumeElement, MuteElement, and PeakMeterElement objects. +4. Create the ACXAUDIOENGINE element. + +Drivers will need to perform similar steps to add an ACXSTREAMAUDIOENGINE element when creating a stream on the Offload pin. + +## Stream resource allocation  + +The streaming model for ACX is packet-based, with support for one or two packets for a stream. The Render or Capture ACXPIN for the streaming circuit is given a request to allocate the memory packets that are used in the stream. To support Rebalance, the allocated memory must be system memory instead of device memory mapped into the system. The driver may use existing WDF functions to perform the allocation, and will return an array of pointers to the buffer allocations. If the driver requires a single contiguous block, it may allocate both packets as a single buffer, returning a pointer to an offset of the buffer as the second packet. + +If a single packet is allocated, the packet must be page-aligned and is mapped twice into user mode: + +| packet 0 | packet 0 | + +This enables GetBuffer to return a pointer to a single contiguous memory buffer that may span from the end of the buffer to the beginning without requiring the application to handle wrapping the memory access.  + +If two packets are allocated, they are mapped into user mode :  + +| packet 0 | packet 1 | + +With the initial ACX packet streaming, there are only two packets allocated at the beginning. The client virtual memory mapping will remain valid without changing for the life of the stream once the allocation and mapping has been performed. There is one event associated with the stream to indicate packet completion for both packets. There will also be a shared buffer that the ACX framework will use to communicate which packet finished with the event. +  +### Large buffer streams packet sizes + +When exposing support for Large Buffers, the driver will also provide a callback that is used to determine the minimum and maximum packet sizes for Large Buffer playback. +  +The packet size for stream buffer allocation is determined based on the minimum and maximum. + +Since the minimum and maximum buffer sizes may be volatile, the driver can fail the packet allocation call if the minimum and maximum have changed. + +### Specifying ACX buffer constraints + +To specify ACX buffer constraints, ACX drivers can use the KS/PortCls properties setting - [KSAUDIO_PACKETSIZE_CONSTRAINTS2](/windows-hardware/drivers/ddi/ksmedia/ns-ksmedia-_ksaudio_packetsize_constraints2) and the [KSAUDIO_PACKETSIZE_PROCESSINGMODE_CONSTRAINT structure](/windows-hardware/drivers/ddi/ksmedia/ns-ksmedia-_ksaudio_packetsize_signalprocessingmode_constraint). + +The following code sample shows how to set buffer size constraints for WaveRT buffers for different signal processing modes. + +```cpp +// +// Describe buffer size constraints for WaveRT buffers +// Note: 10msec for each of the Modes is the default system behavior. +// +static struct +{ + KSAUDIO_PACKETSIZE_CONSTRAINTS2 TransportPacketConstraints; // 1 + KSAUDIO_PACKETSIZE_PROCESSINGMODE_CONSTRAINT AdditionalProcessingConstraints[4]; // + 4 = 5 +} DspR_RtPacketSizeConstraints = +{ + { + 10 * HNSTIME_PER_MILLISECOND, // 10 ms minimum processing interval + FILE_BYTE_ALIGNMENT, // 1 byte packet size alignment + 0, // no maximum packet size constraint + 5, // 5 processing constraints follow + { + STATIC_AUDIO_SIGNALPROCESSINGMODE_RAW, // constraint for raw processing mode + 0, // NA samples per processing frame + 10 * HNSTIME_PER_MILLISECOND, // 100000 hns (10ms) per processing frame + }, + }, + { + { + STATIC_AUDIO_SIGNALPROCESSINGMODE_DEFAULT, // constraint for default processing mode + 0, // NA samples per processing frame + 10 * HNSTIME_PER_MILLISECOND, // 100000 hns (10ms) per processing frame + }, + { + STATIC_AUDIO_SIGNALPROCESSINGMODE_COMMUNICATIONS, // constraint for movie communications mode + 0, // NA samples per processing frame + 10 * HNSTIME_PER_MILLISECOND, // 100000 hns (10ms) per processing frame + }, + { + STATIC_AUDIO_SIGNALPROCESSINGMODE_MEDIA, // constraint for default media mode + 0, // NA samples per processing frame + 10 * HNSTIME_PER_MILLISECOND, // 100000 hns (10ms) per processing frame + }, + { + STATIC_AUDIO_SIGNALPROCESSINGMODE_MOVIE, // constraint for movie movie mode + 0, // NA samples per processing frame + 10 * HNSTIME_PER_MILLISECOND, // 100000 hns (10ms) per processing frame + }, + } +}; +``` + +A DSP_DEVPROPERTY structure is used to store the constraints. + +```cpp +typedef struct _DSP_DEVPROPERTY { + const DEVPROPKEY *PropertyKey; + DEVPROPTYPE Type; + ULONG BufferSize; + __field_bcount_opt(BufferSize) PVOID Buffer; +} DSP_DEVPROPERTY, PDSP_DEVPROPERTY; +``` + +And an array of those structures is created. + +```cpp +const DSP_DEVPROPERTY DspR_InterfaceProperties[] = +{ + { + &DEVPKEY_KsAudio_PacketSize_Constraints2, // Key + DEVPROP_TYPE_BINARY, // Type + sizeof(DspR_RtPacketSizeConstraints), // BufferSize + &DspR_RtPacketSizeConstraints, // Buffer + }, +}; +``` + +Later in the EvtCircuitCompositeCircuitInitialize function, the AddPropertyToCircuitInterface helper function is used to add the array of interface properties to the circuit. + +```cpp + // Set RT buffer constraints. + // + status = AddPropertyToCircuitInterface(Circuit, ARRAYSIZE(DspC_InterfaceProperties), DspC_InterfaceProperties); +``` + +The AddPropertyToCircuitInterface helper function takes the [AcxCircuitGetSymbolicLinkName](/windows-hardware/drivers/ddi/acxcircuit/nf-acxcircuit-acxcircuitgetsymboliclinkname) for the circuit and then calls [IoGetDeviceInterfaceAlias](/windows-hardware/drivers/ddi/wdm/nf-wdm-iogetdeviceinterfacealias) to locate the audio interface used by the circuit. + +Then the SetDeviceInterfacePropertyDataMultiple function calls [IoSetDeviceInterfacePropertyData function](/windows-hardware/drivers/ddi/wdm/nf-wdm-iosetdeviceinterfacepropertydata) to modify the current value of the device interface property - the KS audio property values on the audio interface for the ACXCIRCUIT. + +```cpp +PAGED_CODE_SEG +NTSTATUS AddPropertyToCircuitInterface( + _In_ ACXCIRCUIT Circuit, + _In_ ULONG PropertyCount, + _In_reads_opt_(PropertyCount) const DSP_DEVPROPERTY * Properties +) +{ + PAGED_CODE(); + + NTSTATUS status = STATUS_UNSUCCESSFUL; + UNICODE_STRING acxLink = {0}; + UNICODE_STRING audioLink = {0}; + WDFSTRING wdfLink = AcxCircuitGetSymbolicLinkName(Circuit); + bool freeStr = false; + + // Get the underline unicode string. + WdfStringGetUnicodeString(wdfLink, &acxLink); + + // Make sure there is a string. + if (!acxLink.Length || !acxLink.Buffer) + { + status = STATUS_INVALID_DEVICE_STATE; + DrvLogError(g_BthLeVDspLog, FLAG_INIT, + L"AcxCircuitGetSymbolicLinkName failed, Circuit: %p, %!STATUS!", + Circuit, status); + goto exit; + } + + // Get the audio interface. + status = IoGetDeviceInterfaceAlias(&acxLink, &KSCATEGORY_AUDIO, &audioLink); + if (!NT_SUCCESS(status)) + { + DrvLogError(g_BthLeVDspLog, FLAG_INIT, + L"IoGetDeviceInterfaceAlias failed, Circuit: %p, symbolic link name: %wZ, %!STATUS!", + Circuit, &acxLink, status); + goto exit; + } + + freeStr = true; + + // Set specified properties on the audio interface for the ACXCIRCUIT. + status = SetDeviceInterfacePropertyDataMultiple(&audioLink, PropertyCount, Properties); + if (!NT_SUCCESS(status)) + { + DrvLogError(g_BthLeVDspLog, FLAG_INIT, + L"SetDeviceInterfacePropertyDataMultiple failed, Circuit: %p, symbolic link name: %wZ, %!STATUS!", + Circuit, &audioLink, status); + goto exit; + } + + status = STATUS_SUCCESS; + +exit: + + if (freeStr) + { + RtlFreeUnicodeString(&audioLink); + freeStr = false; + } + + return status; +} +``` +  +### Stream state changes + +When a stream state change occurs, each stream object in the Endpoint Audio Path for the stream will receive a notification event from the ACX framework. The order in which this happens depends on the state change and the flow of the stream. + +- For Render streams going from a less-active state to a more-active state, the streaming circuit (which registered the SINK) will receive the event first. Once it’s handled the event, the next circuit in the Endpoint Audio Path will receive the event. +- For Render streams going from a more-active state to a less-active state, the streaming circuit will receive the event last.  + +- For Capture streams going from a less-active state to a more-active state, the streaming circuit will receive the event last.  +- For Capture streams going from a more-active state to a less-active state, the streaming circuit will receive the event first.  + +The above ordering is the default provided by the ACX framework. A driver can request the opposite behavior by setting AcxStreamBridgeInvertChangeStateSequence (defined in [ACX_STREAM_BRIDGE_CONFIG_FLAGS](/windows-hardware/drivers/ddi/acxstreams/ne-acxstreams-acx_stream_bridge_config_flags)) when creating the ACXSTREAMBRIDGE that the driver adds to the streaming circuit. +  +### Streaming audio data  + +Once the stream is created and the appropriate buffers are allocated, the stream is in the Pause state awaiting stream start. When the client puts the stream into Play state, the ACX framework will call all ACXSTREAM objects associated with the stream to indicate the stream state is in Play. The ACXPIN will then be placed in the Play state, at which point data will start flowing.  + +#### Rendering audio data + +Once the stream is created and the resources are allocated, the application will call Start on the stream to start playback. Note that an application should call GetBuffer/ReleaseBuffer before starting the stream to ensure the first packet that will start playing immediately will have valid audio data.  + +The client starts by pre-rolling a buffer. When the client calls ReleaseBuffer, this will translate to a call in AudioKSE that will call into the ACX layer, which will call [EvtAcxStreamSetRenderPacket](/windows-hardware/drivers/ddi/acxstreams/nc-acxstreams-evt_acx_stream_set_render_packet) on the active ACXSTREAM. The property will include the packet index (0-based) and, if appropriate, an EOS flag with the byte offset of the end of the stream in the current packet.  +  +After the streaming circuit finishes with a packet, it will trigger the buffer-complete notification that will release clients waiting to fill the next packet with render audio data.  + +The Timer Driven streaming mode is supported and is indicated by using a PacketCount value of 1 when calling the driver's [EvtAcxStreamAllocateRtPackets](/windows-hardware/drivers/ddi/acxstreams/nc-acxstreams-evt_acx_stream_allocate_rtpackets) callback. + +#### Capturing audio data + +Once the stream is created and the resources are allocated, the application will call Start on the stream to start playback.  + +When the stream is running, the source circuit fills the capture packet with audio data. Once the first packet is filled, the source circuit releases the packet to the ACX framework. At this point the ACX framework signals the stream notification event.  + +Once the stream notification has been signaled, the client can send [KSPROPERTY_RTAUDIO_GETREADPACKET](./ksproperty-rtaudio-getreadpacket.md) to get the index (0-based) of the packet that’s finished capturing. When the client has sent GETCAPTUREPACKET, the driver can assume all previous packets have been processed and are available for filling.  + +For Burst capture, the source circuit can release a new packet to the ACX framework as soon as GETREADPACKET has been called. + +The client can also use [KSPROPERTY_RTAUDIO_PACKETVREGISTER](/windows-hardware/drivers/ddi/ksmedia/ns-ksmedia-ksrtaudio_packetvregister_property) to get a pointer to the RTAUDIO_PACKETVREGISTER structure for the stream. This structure will be updated by the ACX framework before signaling packet complete. + +##### Legacy KS kernel streaming behavior + +There can be situations, such as when a driver implements burst capture (as in a key word spotter implementation), where the legacy kernel streaming packet handling behavior needs to be used instead of the PacketVRegister. To use the previous packet-based behavior, the driver should return STATUS_NOT_SUPPORTED for [KSPROPERTY_RTAUDIO_PACKETVREGISTER](/windows-hardware/drivers/ddi/ksmedia/ns-ksmedia-ksrtaudio_packetvregister_property). + +The following sample shows how to do this in the [AcxStreamInitAssignAcxRequestPreprocessCallback](/windows-hardware/drivers/ddi/acxstreams/nf-acxstreams-acxstreaminitassignacxrequestpreprocesscallback) for an ACXSTREAM. For more information see [AcxStreamDispatchAcxRequest](/windows-hardware/drivers/ddi/acxstreams/nf-acxstreams-acxstreamdispatchacxrequest). + +```cpp +Circuit_EvtStreamRequestPreprocess( + _In_ ACXOBJECT Object, + _In_ ACXCONTEXT DriverContext, + _In_ WDFREQUEST Request) +{ + ACX_REQUEST_PARAMETERS params; + PCIRCUIT_STREAM_CONTEXT streamCtx; + + streamCtx = GetCircuitStreamContext(Object); + // The driver would define the pin type to track which pin is the keyword pin. + // The driver would add this to the driver-defined context when the stream is created. + // The driver would use AcxStreamInitAssignAcxRequestPreprocessCallback to set + // the Circuit_EvtStreamRequestPreprocess callback for the stream. + if (streamCtx && streamCtx->PinType == CapturePinTypeKeyword) + { + if (IsEqualGUID(params.Parameters.Property.Set, KSPROPSETID_RtAudio) && + params.Parameters.Property.Id == KSPROPERTY_RTAUDIO_PACKETVREGISTER) + { + status = STATUS_NOT_SUPPORTED; + outDataCb = 0; + + WdfRequestCompleteWithInformation(Request, status, outDataCb); + return; + } + } + + (VOID)AcxStreamDispatchAcxRequest((ACXSTREAM)Object, Request); +} +``` + +#### Stream position  + +The ACX framework will call the [EvtAcxStreamGetPresentationPosition](/windows-hardware/drivers/ddi/acxstreams/nc-acxstreams-evt_acx_stream_get_presentation_position) callback to get the current stream position. The current stream position will include the PlayOffset and the WriteOffset.  + +The WaveRT streaming model allows the audio driver to expose a HW Position register to the client. The ACX streaming model will not support exposing any HW registers since these would prevent a rebalance from happening.  + +Each time the streaming circuit completes a packet, it calls [AcxRtStreamNotifyPacketComplete](/windows-hardware/drivers/ddi/acxstreams/nf-acxstreams-acxrtstreamnotifypacketcomplete) with the 0-based packet index and the QPC value taken as close to packet completion as possible (as an example, the QPC value can be calculated by the Interrupt Service Routine). This information is available to clients through [KSPROPERTY_RTAUDIO_PACKETVREGISTER](/windows-hardware/drivers/ddi/ksmedia/ns-ksmedia-ksrtaudio_packetvregister_property), which returns a pointer to a structure that contains the CompletedPacketCount, the CompletedPacketQPC, and a value that combines the two (which allows the client to ensure the CompletedPacketCount and CompletedPacketQPC are from the same packet). +  +#### Stream state transitions + +After a stream has been created, ACX will transition the stream to different states using the following callbacks: + +- [EvtAcxStreamPrepareHardware](/windows-hardware/drivers/ddi/acxstreams/nc-acxstreams-evt_acx_stream_prepare_hardware) will transition the stream from the AcxStreamStateStop state to the AcxStreamStatePause state. The driver should reserve required hardware such as DMA Engines when it receives EvtAcxStreamPrepareHardware. +- [EvtAcxStreamRun](/windows-hardware/drivers/ddi/acxstreams/nc-acxstreams-evt_acx_stream_run) will transition the stream from the AcxStreamStatePause state to the AcxStreamStateRun state. +- [EvtAcxStreamPause](/windows-hardware/drivers/ddi/acxstreams/nc-acxstreams-evt_acx_stream_pause) will transition the stream from the AcxStreamStateRun state to the AcxStreamStatePause state. +- [EvtAcxStreamReleaseHardware](/windows-hardware/drivers/ddi/acxstreams/nc-acxstreams-evt_acx_stream_release_hardware) will transition the stream from the AcxStreamStatePause state to the AcxStreamStateStop state. The driver should release required hardware such as DMA engines when it receives EvtAcxStreamReleaseHardware. + +The stream can receive the EvtAcxStreamPrepareHardware callback after it has received the EvtAcxStreamReleaseHardware callback. This will transition the stream back to the AcxStreamStatePause state. + +Packet allocation with EvtAcxStreamAllocateRtPackets will normally happen before the first call to EvtAcxStreamPrepareHardware. The allocated packets will normally be freed with EvtAcxStreamFreeRtPackets after the last call to EvtAcxStreamReleaseHardware. This ordering is not guaranteed. + +The AcxStreamStateAcquire state is not used. ACX removes the need for the driver to have the acquire state, as this state is implicit with the prepare hardware ([EvtAcxStreamPrepareHardware](/windows-hardware/drivers/ddi/acxstreams/nc-acxstreams-evt_acx_stream_prepare_hardware)) and release hardware ([EvtAcxStreamReleaseHardware](/windows-hardware/drivers/ddi/acxstreams/nc-acxstreams-evt_acx_stream_release_hardware)) callbacks. + +#### Stream close + +When the client closes the stream, the driver will receive EvtAcxStreamPause and EvtAcxStreamReleaseHardware before the ACXSTREAM object is deleted by the ACX Framework. The driver can supply the standard WDF EvtCleanupCallback entry in the [WDF_OBJECT_ATTRIBUTES structure](/windows-hardware/drivers/ddi/wdfobject/ns-wdfobject-_wdf_object_attributes) when calling AcxStreamCreate to perform final cleanup for the ACXSTREAM. WDF will call EvtCleanupCallback when the framework attempts to delete the object. Do not use EvtDestroyCallback, which is only called once all references to the object have been released which is indeterminant. + +The driver should clean up system memory resources associated with the ACXSTREAM object in EvtCleanupCallback if the resources haven't already been cleaned up in EvtAcxStreamReleaseHardware. + +#### Stream surprise removal and invalidation  + +If the driver determines the stream has become invalid (e.g. the jack goes unplugged), the circuit will shut down all streams.  +  +### Large buffer streams and offload engine support  + +ACX uses the ACXAUDIOENGINE element to designate an ACXPIN that will handle Offload stream creation and the different elements required for offload stream volume, mute, and peak meter state. This is similar to the existing audio engine node in WaveRT drivers. + +## Streaming DDIs + +### Streaming structures + +#### [ACX_RTPACKET structure](/windows-hardware/drivers/ddi/acxstreams/ns-acxstreams-acx_rtpacket) + +This structure represents a single allocated packet. The PacketBuffer can be a WDFMEMORY handle, an MDL, or a Buffer. It has an associated initialization function, [ACX_RTPACKET_INIT](/windows-hardware/drivers/ddi/acxstreams/nf-acxstreams-acx_rtpacket_init). + +#### [ACX_STREAM_CALLBACKS](/windows-hardware/drivers/ddi/acxstreams/ns-acxstreams-acx_stream_callbacks) + +This structure identifies the driver callbacks for streaming to the ACX framework. This structure is a part of the [ACX_PIN_CONFIG structure](/windows-hardware/drivers/ddi/acxpin/ns-acxpin-acx_pin_config). + +### Streaming callbacks + +#### EvtAcxStreamAllocateRtPackets + +The [EvtAcxStreamAllocateRtPackets](/windows-hardware/drivers/ddi/acxstreams/nc-acxstreams-evt_acx_stream_allocate_rtpackets) event tells the driver to allocate RtPackets for streaming. An AcxRtStream will receive PacketCount = 2 for event driven streaming or PacketCount = 1 for timer based streaming. If the driver uses a single buffer for both packets, the second RtPacketBuffer should have a [WDF_MEMORY_DESCRIPTOR](/windows-hardware/drivers/ddi/wdfmemory/ns-wdfmemory-_wdf_memory_descriptor) with Type = WdfMemoryDescriptorTypeInvalid with an RtPacketOffset that aligns with the end of the first packet (packet[2].RtPacketOffset = packet[1].RtPacketOffset+packet[1].RtPacketSize). + +#### EvtAcxStreamFreeRtPackets + +The [EvtAcxStreamFreeRtPackets](/windows-hardware/drivers/ddi/acxstreams/nc-acxstreams-evt_acx_stream_free_rtpackets) event tells the driver to free the RtPackets that were allocated in a previous call to EvtAcxStreamAllocateRtPackets. The same packets from that call are included. + +#### EvtAcxStreamGetHwLatency + +The [EvtAcxStreamGetHwLatency](/windows-hardware/drivers/ddi/acxstreams/nc-acxstreams-evt_acx_stream_get_hw_latency) event tells the driver to provide stream latency for the specific circuit of this stream (overall latency will be a sum of the latency of the different circuits). The FifoSize is in bytes and the Delay is in 100-nanosecond units. + +#### EvtAcxStreamSetRenderPacket + +The [EvtAcxStreamSetRenderPacket](/windows-hardware/drivers/ddi/acxstreams/nc-acxstreams-evt_acx_stream_set_render_packet) event tells the driver which packet was just released by the client. If there are no glitches, this packet should be (CurrentRenderPacket + 1), where CurrentRenderPacket is the packet the driver is currently streaming from. + +Flags can be 0 or AcxStreamSetRenderPacketEndOfStream, indicating the Packet is the last packet in the stream, and EosPacketLength is a valid length in bytes for the packet. + +The driver should continue to increase the CurrentRenderPacket as packets are rendered instead of changing its CurrentRenderPacket to match this value. + +#### EvtAcxStreamGetCurrentPacket + +The [EvtAcxStreamGetCurrentPacket](/windows-hardware/drivers/ddi/acxstreams/nc-acxstreams-evt_acx_stream_get_current_packet) tells the driver to indicate which packet (0-based) is currently being rendered to the hardware or is currently being filled by the capture hardware. + +#### EvtAcxStreamGetCapturePacket + +The [EvtAcxStreamGetCapturePacket](/windows-hardware/drivers/ddi/acxstreams/nc-acxstreams-evt_acx_stream_get_capture_packet) tells the driver to indicate which packet (0-based) was completely filled most recently, including the QPC value at the time the driver started filling the packet. + +#### EvtAcxStreamGetPresentationPosition + +The [EvtAcxStreamGetPresentationPosition](/windows-hardware/drivers/ddi/acxstreams/nc-acxstreams-evt_acx_stream_get_presentation_position) tells the driver to indicate the current position along with the QPC value at the time the current position was calculated. + +### STREAM STATE EVENTS + +The streaming state for an ACXSTREAM is managed by the following APIs. + +[EVT_ACX_STREAM_PREPARE_HARDWARE](/windows-hardware/drivers/ddi/acxstreams/nc-acxstreams-evt_acx_stream_prepare_hardware) + +[EVT_ACX_STREAM_RELEASE_HARDWARE](/windows-hardware/drivers/ddi/acxstreams/nc-acxstreams-evt_acx_stream_release_hardware) + +[EVT_ACX_STREAM_RUN](/windows-hardware/drivers/ddi/acxstreams/nc-acxstreams-evt_acx_stream_run) + +[EVT_ACX_STREAM_PAUSE](/windows-hardware/drivers/ddi/acxstreams/nc-acxstreams-evt_acx_stream_pause) + +### Streaming ACX APIs + +#### [AcxStreamCreate](/windows-hardware/drivers/ddi/acxstreams/nf-acxstreams-acxstreamcreate) + +AcxStreamCreate creates an ACX Stream that can be used to control streaming behavior. + +#### [AcxRtStreamCreate](/windows-hardware/drivers/ddi/acxstreams/nf-acxstreams-acxrtstreamcreate) + +AcxRtStreamCreate creates an ACX Stream that can be used to control streaming behavior and handle packet allocation and communicate streaming state. + +#### [AcxRtStreamNotifyPacketComplete](/windows-hardware/drivers/ddi/acxstreams/nf-acxstreams-acxrtstreamnotifypacketcomplete) + +The driver calls this ACX API when a packet has completed. The packet completion time and the 0-based Packet index are included to improve client performance. The ACX framework will set any notification events associated with the stream. + +## See also + +[ACX audio class extensions overview](acx-audio-class-extensions-overview.md) + +[ACX reference documentation](acx-reference.md) + +[Summary of ACX Objects](acx-summary-of-objects.md) diff --git a/windows-driver-docs-pr/audio/acx-summary-of-objects.md b/windows-driver-docs-pr/audio/acx-summary-of-objects.md index 0cc5d0addf..e915045e30 100644 --- a/windows-driver-docs-pr/audio/acx-summary-of-objects.md +++ b/windows-driver-docs-pr/audio/acx-summary-of-objects.md @@ -1,21 +1,20 @@ --- -title: Summary of ACX Objects -description: This topic provided a high level summary of ACX Objects that form the base of an ACX audio driver. -ms.date: 07/28/2022 +title: Summary of ACX objects +description: This topic provides a high level summary of ACX objects that form the base of an ACX audio driver. +ms.date: 04/19/2023 ms.localizationpriority: medium --- -# Summary of ACX Objects +# Summary of ACX objects >[!IMPORTANT] > Some information relates to a prerelease product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here. -This topic provided a high level summary of Audio Class Extensions (ACX) Objects that form the base of an ACX audio driver. For a general overview of ACX, see [ACX Audio Class Extensions Overview](acx-audio-class-extensions-overview.md). +This topic provides a high level summary of Audio Class Extensions (ACX) objects that form the base of an ACX audio driver. For a general overview of ACX, see [ACX audio class extensions overview](acx-audio-class-extensions-overview.md). ACX objects are Windows Driver Framework (WDF) objects - WDFOBJECT. For more information about WDF see [Introduction to Framework Objects](../wdf/introduction-to-framework-objects.md). For a summary of WDF objects see [Summary of Framework Objects](../wdf/summary-of-framework-objects.md). - -## ACX Object Hierarchy +## ACX object hierarchy In ACX (as in WDF), the driver object is the root object, and all other objects are its children/descendants. All ACX objects are children of the driver object directly or indirectly via other ACX or WDF objects. An ACX driver can specify the parent of an ACX object during creation time. If the parent is not specified, ACX uses a default parent as described in these sections. @@ -23,15 +22,15 @@ In ACX (as in WDF), the driver object is the root object, and all other objects ## ACX Circuit -An AcxCircuit represents a partial or full audio path to a user perceived audio device (speakers, mic, etc.). An AcxCircuit has at least one input pin and one output pin (ACXPIN), and it may aggregate one or more AcxElements-like objects. By default, AcxElements are ‘connected’ in the same order of assembly. +An AcxCircuit represents a partial or full audio path to a user perceived audio device (speakers, mic, etc.). An AcxCircuit has at least one input pin and one output pin (ACXPIN), and it may aggregate one or more AcxElements-like objects. By default, AcxElements are ‘connected’ in the same order of assembly. The audio circuit is the core building block of ACX. In the new ACX framework, an audio driver creates one or more ACX circuit objects to represent a partial or complete audio data/control path. ACX assembles these ACX circuit objects together to create a complete audio path which represents an audio endpoint. ACX is responsible for managing the ACX circuits and their dependencies. The order on how these circuits are assembled can be statically defined at initialization time or dynamically defined at run time. -An audio endpoint in the ACX frameworks is a collection of one or more ACX circuits. Each ACX circuit in a multi-circuit audio path must belong to a different PnP device stack. An ACX driver may create one or more circuits at initialization time, or it may create circuits at run time, as side effect of an external event, such as after detecting a new audio component, or because it registered itself with ACX as a factory for a specific circuit type, and ACX framework asked the factory component to create a new circuit of that type (see ACX circuit manager/factory described later in this topic). +An audio endpoint in the ACX frameworks is a collection of one or more ACX circuits. Each ACX circuit in a multi circuit audio path must belong to a different PnP device stack. An ACX driver may create one or more circuits at initialization time, or it may create circuits at run time, as side effect of an external event, such as after detecting a new audio component, or because it registered itself with ACX as a factory for a specific circuit type, and ACX framework asked the factory component to create a new circuit of that type (see ACX circuit manager/factory described later in this topic). - An AcxCircuit may have one or more streams. -- An AcxCircuit has a dedicated WDF queue. For more information about WDF queues, see [Framework Queue Objects](../wdf/framework-queue-objects.md). +- An AcxCircuit has a dedicated WDF queue. For more information about WDF queues, see [Framework Queue Objects](../wdf/creating-i-o-queues.md). The DDIs for ACX circuits are described in the [acxcircuit.h](/windows-hardware/drivers/ddi/acxcircuit) header. @@ -45,7 +44,7 @@ The DDIs for Pin are described in the [acxpin.h](/windows-hardware/drivers/ddi/a An AcxStream represents an audio stream on a specific circuit’s hardware. An AcxStream may aggregate one or more AcxElements-like objects. By default, AcxElements are ‘connected’ in the same order of assembly. An AcxStream is associated with only one ACX circuit. -- An AcxStream has a dedicated WDF queue. For more information about WDF queues, see [Framework Queue Objects](../wdf/framework-queue-objects.md) +- An AcxStream has a dedicated WDF queue. For more information about WDF queues, see [Framework Queue Objects](../wdf/creating-i-o-queues.md) - An AcxStream support different states. These states indicate when audio is flowing (RUN state) or not flowing (PAUSE or STOP state). - Currently ACX supports two types of streams: basic ACX stream objects used by non-streaming circuits, and ACX RT stream objects used by streaming circuits. @@ -67,11 +66,11 @@ The DDIs for targets are defined in the [acxtargets.h](/windows-hardware/drivers ## ACX Stream Bridge -The AcxStreamBridge object is used by a circuit to propagate a stream creation, stream’s states transitions and DRM settings between circuit segments. This object is only used in a multi-circuit (audio composite) scenario. A driver may associate one or more ACXSTREAMBRIDGE objects to a bridge pin. A bridge pin is the ACXPIN that logically connects to the correspoinding ACXPIN on the other circuit. +The AcxStreamBridge object is used by a circuit to propagate a stream creation, stream’s states transitions and DRM settings between circuit segments. This object is only used in a multi circuit (audio composite) scenario. A driver may associate one or more ACXSTREAMBRIDGE objects to a bridge pin. A bridge pin is the ACXPIN that logically connects to the correspoinding ACXPIN on the other circuit. The DDIs for Stream are described in the [acxstreams.h](/windows-hardware/drivers/ddi/acxstreams) header. -## Example of ACX Audio Engine Node Circuit layout +## Example of ACX audio engine node circuit layout The following diagram illustrates an ACX circuit. The host and offload pins are inputs to the circuit with a loopback pin that could be used for echo cancellation. The output could be a bridge pin that routes to a speaker. @@ -89,7 +88,7 @@ The ACX manager is used for system tasks such as supporting composite audio endp The ACX Object Bag is used to store various data types. ACXOBJECTBAG can be passed as argument in various DDIs. The DDIs for Object Bag are described in the [acxmisc.h](/windows-hardware/drivers/ddi/acxmisc/) header. -## ACX Object Summary +## ACX object summary The following table lists all of the ACX objects and provides some basic information about each object. @@ -120,7 +119,7 @@ The following table lists all of the ACX objects and provides some basic informa | ACXTARGETSTREAM | Target Stream | Used to communicate with a remote circuit’s stream exposed by a different stack. | | ACXTARGETFACTORYCIRCUIT | Target Circuit Factory | Used to communicate with a remote circuit's factory. | | ACXSTREAMBRIDGE | Stream Bridge | Used by a circuit to propagate a stream creation, states transitions and DRM between circuit segments. | -| ACXCOMPOSITE | Composite | Used to represent multi-circuit/multi-stack/multiple-vendors stream architectures. | +| ACXCOMPOSITE | Composite | Used to represent multi circuit/multi-stack/multiple-vendors stream architectures. | | ACXCOMPOSITEFACTORY | Composite Factory | A factory that creates composite audio circuits. | | ACXFACTORYCIRCUIT | Factory Circuit | A factory that creates circuits using a specific template. | | ACXCIRCUITMANAGER | Circuit Manager | A circuit provider that is used for dynamic circuit creation. | @@ -128,7 +127,6 @@ The following table lists all of the ACX objects and provides some basic informa | ACXCIRCUITTEMPLATE | Circuit Template | A circuit template represent a partial audio path. | | ACXAUDIOMODULE | Audio Module | For custom 3rd party add on functionality. | - The following ACX objects are used to store circuit, stream and circuit factory information. | Handle | Purpose | @@ -137,9 +135,8 @@ The following ACX objects are used to store circuit, stream and circuit factory | ACXSTREAM_INIT | Stores ACX stream initialization data | | ACXFACTORYCIRCUIT_INIT | Stores initialization data used by an ACX circuit factory | - ## See also -[ACX Audio Class Extensions overview](acx-audio-class-extensions-overview.md) +[ACX audio class extensions overview](acx-audio-class-extensions-overview.md) -[ACX multi stack cross driver communications](acx-audio-multi-stack.md) \ No newline at end of file +[ACX reference documentation](acx-reference.md) diff --git a/windows-driver-docs-pr/audio/acx-targets.md b/windows-driver-docs-pr/audio/acx-targets.md new file mode 100644 index 0000000000..487bb6a29b --- /dev/null +++ b/windows-driver-docs-pr/audio/acx-targets.md @@ -0,0 +1,83 @@ +--- +title: ACX targets and driver synchronization +description: This topic provides a high level summary of the ACX targets and driver synchronization. +ms.date: 04/19/2023 +ms.localizationpriority: medium +--- + +# ACX targets and driver synchronization + +>[!IMPORTANT] +> Some information relates to a prerelease product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here. + +This topic provides a summary of the Audio Class eXtensions (ACX) targets and driver synchronization. + +For general information about the ACX, see [ACX audio class extensions overview](acx-audio-class-extensions-overview.md) and [Summary of ACX Objects](acx-summary-of-objects.md). For information about IRPs, see [ACX IO request packet IRPs](acx-irps.md). + +## ACX targets + +ACX uses [WdfIoTarget](/windows-hardware/drivers/ddi/wdfiotarget/) to facilitate communications between ACX objects, circuits, pins, streams, elements and circuit factories. WdfIoTarget is an existing WDF abstraction to facilitate the communication between two different stacks. + +Drivers use [AcxTargetCircuit](/windows-hardware/drivers/ddi/acxtargets/) to communicate with a remote circuit exposed by a different stack. AcxTargetCircuit is implemented using a WdfIoTarget. + +Drivers use [AcxTargetPin](/windows-hardware/drivers/ddi/acxpin/) to communicate with a remote circuit’s pin exposed by a different stack. AcxTargetPin is implemented using a WdfIoTarget to send messages to the remote pin entity. + +Drivers use [AcxTargetStream](/windows-hardware/drivers/ddi/acxstreams/) to communicate with a remote circuit’s stream exposed by a different stack. AcxTargetStream is implemented using a WdfIoTarget to create a remote stream and change the state of the remote stream. + +Drivers use [AcxTargetElement](/windows-hardware/drivers/ddi/acxtargets/) to communicate with a remote circuit’s element exposed by a different stack. AcxTargetElement is implemented using a WdfIoTarget to send messages to the remote element entity. + +Drivers use [AcxTargetFactoryCircuit](/windows-hardware/drivers/ddi/acxtargets/) to communicate with a remote circuit factory instance. AcxTargetFactoryCircuit is implemented using a WdfTarget to send messages to the remote circuit factory. + +To interact with the remote circuit, each of the ACX types listed above supports: + +- properties +- methods +- events + +All these types are built on top of the [WdfIoTarget](/windows-hardware/drivers/ddi/wdfiotarget/) object types. + +This diagram shows the ACX target architecture and the inheritance from the WDF Driver and Device objects. + +![diagram illustrating the acx target architecture showing WDFDRIVER, WDFDEVICE, and under that ACXTARGET, ACXSTREAM ACXSTREAMFACTORY with the lowest layer showing ACXTARGETELEMENT and ACXTARGETPIN](images/audio-acx-multi-stack-acxtarget-objects.png) + +## ACX driver synchronization and serialization + +The term synchronization is a general term, and it is used to reference the operations needed to share resources (memory, I/O, etc.) between multiple concurrent clients. + +The term serialization is used to reference one type of synchronization for one type of object (I/O requests, callbacks, etc.). + +ACX Drivers are WDF Drivers, which means that the synchronization of ACX Drivers is based on the synchronization capabilities of WDF: + +- The use of reference counts and the hierarchical object model. +- Driver-configurable flow control for I/O queues. +- Object presentation lock for device objects and I/O queues. +- Automatic serialization of Plug and Play and power callbacks. + +For an in-depth description of Synchronization and Serialization, see [Using Automatic Synchronization](../wdf/using-automatic-synchronization.md). For a more complete explanation, see the [Developing Drivers with Windows Driver Foundation](../wdf/developing-drivers-with-wdf.md) Microsoft Press Book. + +WDF supports the following synchronization scopes: + +- No scope (default in KMDF). +- Device scope, WDF acquires the device object presentation lock to serialize operations. + +The default ACX queue is a passive, serial queue with no locking. The driver must complete the I/O operation before the next one is delivered. + +ACX doesn’t support the queue scope option. With this option the driver serializes I/O on a specific queue. Different queues may have different synchronization scopes. + +ACX doesn’t support device scope serialization. By default, ACX serializes requests using a serial I/O queue with no locking. Every circuit and stream object have its own dedicated queue. For more info about streaming I/Os please see the ACX Streaming topic. + +If a driver holds a lock, it should never call (explicitly or implicitly) code outside its control until the lock is released. + +For historical reference, the original PortCls uses a synchronization scope like the WDF device scope synchronization, where all I/O for any audio sub-devices created on this device go through the same serialization lock. This type of serialization was, and still is, the cause of various glitches. In later versions of Windows 10 (Version 1511 - TH2) PortCls was updated to use a different lock for stream position I/O requests. + +## See also + +[ACX audio class extensions overview](acx-audio-class-extensions-overview.md) + +[Summary of ACX Objects](acx-summary-of-objects.md) + +[ACX version information](acx-version-overview.md) + +[ACX reference documentation](acx-reference.md) + +[ACX multi stack cross driver communications](acx-multi-stack.md) diff --git a/windows-driver-docs-pr/audio/acx-version-overview.md b/windows-driver-docs-pr/audio/acx-version-overview.md new file mode 100644 index 0000000000..987f6c9705 --- /dev/null +++ b/windows-driver-docs-pr/audio/acx-version-overview.md @@ -0,0 +1,81 @@ +--- +title: ACX version information +description: This topic provides a summary of the ACX and KMDF version information +ms.date: 04/19/2023 +ms.localizationpriority: medium +--- + +# ACX version overview + +>[!IMPORTANT] +> Some information relates to a prerelease product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here. + +This topic discusses ACX and KMDF version information. For a general overview of ACX, see [ACX audio class extensions overview](acx-audio-class-extensions-overview.md). + +## ACX version information + +The current version of ACX is **1.1**. + +Windows OS support for ACX versions are described in the following table. + +| Operating system | KMDF version | Supported ACX version | Version notes | +|--------------------------|--------------|-----------------------|-------------------------| +| Windows 10, version 2004 | 1.31 | 1.1 | Initial public release. | + +## KMDF version information + +ACX objects are Windows Driver Framework (WDF) objects - WDFOBJECT. For more information about WDF, see [Introduction to Framework Objects](../wdf/introduction-to-framework-objects.md). ACX binds to a specific version of KMDF at runtime. For more information, see [KMDF Version History](../wdf/kmdf-version-history.md). + +For information about installing different versions of WDF/KMDF, see the following topics: + +- [Building and Loading a WDF Driver](../wdf/building-and-loading-a-kmdf-driver.md#which-framework-version-should-i-use) + +- [Building a WDF driver for multiple versions of Windows](../wdf/building-a-wdf-driver-for-multiple-versions-of-windows.md) + +- [Specifying the KMDF Co-installer in an INF File](../wdf/installing-the-framework-s-co-installer.md) + +ACX Binds to a specific version of KMDF at runtime. When Windows loads a kernel-mode WDF driver, the driver is dynamically bound to the KMDF run-time library (WdfMM000.sys). Multiple drivers can share the same run-time library (DLL) image, and the run-time libraries for two major versions can co-exist side by side. For information about KMDF versioning, see [Framework Library Versioning](../wdf/framework-library-versioning.md). + +## Multiple ACX version support + +When you build the audio driver, you specify the maximum and minimum version of the ACX framework you want to use at compilation time. Thus, the audio driver at run time can assume that the max/min version of DDI is available, else the audio driver fails to load. + +ACX drivers can be written to run on multiple versions of ACX and at run-time make the call if a specific ACX DDI, structure, etc. is present or not in that version. **ACX_IS_FUNCTION_AVAILABLE(FunctionName)** can be used to see if a specific function in available in a specific version of ACX. For more information, see [ACX_IS_FUNCTION_AVAILABLE macro](/windows-hardware/drivers/ddi/acxfuncenum/nf-acxfuncenum-acx_is_function_available). + +The following code, provides an example on how to check if a function is available. + +```cpp + if (ACX_IS_FUNCTION_AVAILABLE( AcxTargetPinFlushModeDataFormatListCache)) { + DbgPrint("Available: AcxTargetPinFlushModeDataFormatListCache\n"); + } + else + { + DbgPrint("Not available: AcxTargetPinFlushModeDataFormatListCache\n"); + ASSERT(FALSE); + } +``` + +Also available are these similar functions. + +**ACX_IS_STRUCTURE_AVAILABLE(StructName)** described in [ACX_IS_STRUCTURE_AVAILABLE macro](/windows-hardware/drivers/ddi/acxfuncenum/nf-acxfuncenum-acx_is_structure_available). + +**ACX_IS_FIELD_AVAILABLE(StructName, FieldName)** described in [ACX_IS_FIELD_AVAILABLE macro](/windows-hardware/drivers/ddi/acxfuncenum/nf-acxfuncenum-acx_is_field_available). + +ACX also supports the [ACX_DRIVER_VERSION_AVAILABLE_PARAMS_INIT function](/windows-hardware/drivers/ddi/acxdriver/nf-acxdriver-acx_driver_version_available_params_init) which can be used to check version information of the audio driver as shown in the following code sample. + +```cpp + ACX_DRIVER_VERSION_AVAILABLE_PARAMS_INIT(&ver, 1, 1); + if (!AcxDriverIsVersionAvailable(driver, &ver)) + { + ASSERT(FALSE); + goto exit; + } +``` + +## See also + +[ACX_IS_FUNCTION_AVAILABLE macro](/windows-hardware/drivers/ddi/acxfuncenum/nf-acxfuncenum-acx_is_function_available) + +[ACX audio class extensions overview](acx-audio-class-extensions-overview.md) + +[ACX reference documentation](acx-reference.md) diff --git a/windows-driver-docs-pr/audio/adding-new-digital-formats-to-control-panel.md b/windows-driver-docs-pr/audio/adding-new-digital-formats-to-control-panel.md index 1c394520fc..9979bfcf2f 100644 --- a/windows-driver-docs-pr/audio/adding-new-digital-formats-to-control-panel.md +++ b/windows-driver-docs-pr/audio/adding-new-digital-formats-to-control-panel.md @@ -1,45 +1,31 @@ --- title: Adding New Digital Formats to Control Panel description: Adding New Digital Formats to Control Panel -ms.date: 04/20/2017 +ms.date: 05/05/2023 --- # Adding New Digital Formats to Control Panel - In Windows Vista and later versions of Windows, you can develop a third-party digital audio format that streams over SPDIF and make this format available in Control Panel. After you develop your digital audio format, define a new GUID for the format and use an INF file to install the associated audio driver. The following code from an INF file shows how to add the necessary information about your new digital audio format to the registry: ```inf -[Version] -Signature=$WindowsNT$ -... [DDInstall] AddReg = AddReg.NewDigitalFormat ... -... [AddReg.NewDigitalFormat] -HKLM, %My_SubKey%, "DisplayName",,"ABC Audio" -HKLM, %My_SubKey%, "CustomIcon",,"c:\Program Files\MyVendor\myicon.ico" -HKLM, %My_SubKey%, "TestFile",,"c:\Program Files\MyVendor\testfile.wav" +HKR, %My_SubKey%, "DisplayName",,"ABC Audio" +HKR, %My_SubKey%, "CustomIcon",,"c:\Program Files\MyVendor\myicon.ico" +HKR, %My_SubKey%, "TestFile",,"c:\Program Files\MyVendor\testfile.wav" ... [Strings] -My_SubKey = "SOFTWARE\Microsoft\Windows\CurrentVersion\MMDevices\SPDIF_Formats\{00000682-0000-0010-8000-00aa00389b71}" -... +My_SubKey = "MMDevices\SPDIF_Formats\{00000682-0000-0010-8000-00aa00389b71}" ... ``` -In the preceding example, the GUID shown in the \[Strings\] section is used to illustrate the placement of the GUID that you define for your new digital format. HKLM is used as the standard abbreviation for HKEY\_LOCAL\_MACHINE. - -**Important**  The two HKLM line entries for Mycion.ico and Testfile.wav are required. The "c:\\Program Files\\MyVendor\\" folder has been used to show that you must create an appropriate folder for your driver-related icon and test wave files. - - - - - - - +In the preceding example, the GUID shown in the \[Strings\] section is used to illustrate the placement of the GUID that you define for your new digital format. +**Important**  The two HKR line entries for Mycion.ico and Testfile.wav are required. The "c:\\Program Files\\MyVendor\\" folder has been used to show that you must create an appropriate folder for your driver-related icon and test wave files. diff --git a/windows-driver-docs-pr/audio/audio-device-class-inactivity-timer-implementation.md b/windows-driver-docs-pr/audio/audio-device-class-inactivity-timer-implementation.md index 3d422c4345..f2dc5476b8 100644 --- a/windows-driver-docs-pr/audio/audio-device-class-inactivity-timer-implementation.md +++ b/windows-driver-docs-pr/audio/audio-device-class-inactivity-timer-implementation.md @@ -11,7 +11,7 @@ keywords: - power-conservation mode WDK audio - conservation power mode WDK audio - performance power mode WDK audio -ms.date: 04/20/2017 +ms.date: 09/29/2022 --- # Audio Device Class Inactivity Timer Implementation @@ -20,7 +20,7 @@ ms.date: 04/20/2017 ## -In Windows Server 2003 SP1, Windows XP SP2, and later, the PortCls system driver utilizes the system's power-idle detection capabilities to implement an inactivity timer for its audio clients. PortCls programs two time-out values and a desired idle power state into the timer when it initializes it. PortCls monitors any accesses (such as I/O and property accesses) of the device and effectively resets the timer count on each access. If the timer times out, the system requests a power IRP to place the device in the desired idle state. After the device has been placed in the idle state, PortCls will power the device back up in the event of new access activity. +The PortCls system driver utilizes the system's power-idle detection capabilities to implement an inactivity timer for its audio clients. PortCls programs two time-out values and a desired idle power state into the timer when it initializes it. PortCls monitors any accesses (such as I/O and property accesses) of the device and effectively resets the timer count on each access. If the timer times out, the system requests a power IRP to place the device in the desired idle state. After the device has been placed in the idle state, PortCls will power the device back up in the event of new access activity. PortCls contains hard-coded default values for the idle time-outs and the idle power state. Hardware vendors can optionally override the default values by writing their own values to driver-specific keys in the system registry. In this way, vendors can select the power-idle parameter values that are best-suited to their devices. @@ -28,33 +28,40 @@ Vendors can override the default values of the following power-idle parameters: - *ConservationIdleTime* - This parameter specifies the idle time-out interval when the system is running in power-conservation mode. This is the mode that is typically used when the system is running on battery power. The default value for this parameter is 0, which disables the power-idle timer in conservation mode. The hardware vendor can override the default by writing a DWORD value to the following driver-specific registry key: + This parameter specifies the idle time-out interval when the system is running in power-conservation mode. This is the mode that is typically used when the system is running on battery power. The default value for this parameter is 0, which disables the power-idle timer in conservation mode. The hardware vendor can set the value using an inf file like this. ```inf - \HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Class\xxxx\yyyy\PowerSettings\ConservationIdleTime + [MyAudioDevice.AddReg] + HKR,PowerSettings,ConservationIdleTime,%REG_BINARY%,1e,00,00,00 ``` - Note that *xxxx* represents the Media class GUID (see [System-Supplied Device Setup Classes](../install/system-defined-device-setup-classes-reserved-for-system-use.md)) and *yyyy* represents the name of the driver's subkey under the Media class GUID. The value of the key specifies the time-out interval in seconds. +The preceding INF file fragment shows a hexadecimal (hex) value of "1e" for the *ConservationIdleTime*, and this equates to a 30-second idle timeout. + +FLG_ADDREG_BINVALUETYPE + +The other parameters are used to control how the registry key is added. For example %REG_BINARY% indicates that the data is stored as "raw" data. For more information, see [INF AddReg directive](../install/inf-addreg-directive.md). - *PerformanceIdleTime* - This parameter specifies the idle time-out interval when the system is running in performance mode. This is the mode that is typically used when the system is running on AC power. The default value for this parameter is 0, which disables the power-idle timer in performance mode. The hardware vendor can override the default by writing a DWORD value to the following driver-specific registry key: + This parameter specifies the idle time-out interval when the system is running in performance mode. This is the mode that is typically used when the system is running on AC power. The default value for this parameter is 0, which disables the power-idle timer in performance mode. + + The hardware vendor can set the value using an inf file like this. ```inf - \HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Class\xxxx\yyyy\PowerSettings\PerformanceIdleTime + [MyAudioDevice.AddReg] + HKR,PowerSettings,PerformanceIdleTime,%REG_BINARY%,2c,01,00,00 ``` - - Again, *xxxx* represents the Media class GUID and *yyyy* represents the name of the driver's subkey. The value of the key specifies the time-out interval in seconds. + The value of the key specifies the time-out interval in seconds. In this example, the value of 2c,01 will be 300 seconds, or five minutes. - *IdlePowerState* - This parameter specifies the power state that the device will be placed in if the idle time-out period expires. The default value for this parameter is 0, corresponding to device power state D0 (full power). The hardware vendor can override the default by writing a DWORD value to the following driver-specific registry key: + This parameter specifies the power state that the device will be placed in if the idle time-out period expires. The default value for this parameter is 3, corresponding to device power state D3, which is the lowest-powered device low-power state. The hardware vendor can set the value using an inf file like this. ```inf - \HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Class\xxxx\yyyy\PowerSettings\IdlePowerState + [MyAudioDevice.AddReg] + HKR,PowerSettings,IdlePowerState,%REG_BINARY%,03,00,00,00 ``` - - Again, *xxxx* represents the Media class GUID and *yyyy* represents the name of the driver's subkey. The value placed in the key should be 0, 1, 2, or 3, corresponding to device power state D0, D1, D2, or D3, respectively. + The value placed in the key should be 0, 1, 2, or 3, corresponding to device power state D0, D1, D2, or D3, respectively. The three power-idle registry keys exist only if the device-installation INF file creates them. Before configuring the power-idle timer, PortCls attempts to retrieve the driver-specific power-idle parameters from the registry. PortCls uses the default values in place of any power-idle parameters it does not find in the registry. As explained previously, the default power-idle parameter values disable the idle timer. @@ -66,16 +73,10 @@ For example, a hardware vendor might want to specify the following power-idle pa ```inf [MyAudioDevice.AddReg] -HKR,PowerSettings,ConservationIdleTime,1,1e,00,00,00 -HKR,PowerSettings,PerformanceIdleTime,1,2c,01,00,00 -HKR,PowerSettings,IdlePowerState,1,03,00,00,00 +HKR,PowerSettings,ConservationIdleTime,%REG_BINARY%,1e,00,00,00 +HKR,PowerSettings,PerformanceIdleTime,%REG_BINARY%,2c,01,00,00 +HKR,PowerSettings,IdlePowerState,%REG_BINARY%,03,00,00,00 ``` +## See also -HKR represents the driver's root key in the registry: - -```inf -\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Class\xxxx\yyyy -``` - -Again, *xxxx* represents the Media class GUID and *yyyy* represents the name of the driver's subkey. The **PowerSettings** subkey is specified relative to the path name for the root key. - +[**PoRegisterDeviceForIdleDetection**](/windows-hardware/drivers/ddi/ntifs/nf-ntifs-poregisterdeviceforidledetection) diff --git a/windows-driver-docs-pr/audio/audio-device-messages-for-midi.md b/windows-driver-docs-pr/audio/audio-device-messages-for-midi.md index db607077c9..edf1865046 100644 --- a/windows-driver-docs-pr/audio/audio-device-messages-for-midi.md +++ b/windows-driver-docs-pr/audio/audio-device-messages-for-midi.md @@ -9,55 +9,52 @@ ms.date: 04/22/2020 In Windows XP and later versions of Windows (including Windows Vista), the operating system communicates with musical instrument digital interface (MIDI) input and output drivers by using audio device messages. -Every MIDI input and output driver must have one [DriverProc](/windows/win32/api/mmiscapi/nc-mmiscapi-driverproc) entry-point function to enable or disable the driver. Additionally, it must have an additional entry-point function to process messages from the Windows operating system. In the case of MIDI output drivers, the additional entry-point function is [**modMessage**](/previous-versions/windows/hardware/drivers/ff537532(v=vs.85)), which must be provided by the manufacturer of the MIDI device. This function processes messages that WINMM sends to the MIDI output driver. WINMM is a Windows dynamic link library (DLL) module that contains functions that help the operating system and the MIDI output driver communicate with each other. Specifically, WINMM helps to manage 16-bit multimedia applications that run on Windows. +Every MIDI input and output driver must have one [DriverProc](/windows/win32/api/mmiscapi/nc-mmiscapi-driverproc) entry-point function to enable or disable the driver. Additionally, it must have an additional entry-point function to process messages from the Windows operating system. In the case of MIDI output drivers, the additional entry-point function is [**modMessage**](mod-message.md), which must be provided by the manufacturer of the MIDI device. This function processes messages that WINMM sends to the MIDI output driver. WINMM is a Windows dynamic link library (DLL) module that contains functions that help the operating system and the MIDI output driver communicate with each other. Specifically, WINMM helps to manage 16-bit multimedia applications that run on Windows. Each message received by the **modMessage** function comes with two pointers to DWORD variables (DWORD\_PTR). For some messages, one of these parameters points to a structure that contains additional information from the client, or it points to an empty structure for the driver to fill with information for the client. One example of such a structure is [**MIDIOPENDESC**](/windows/win32/api/mmddk/ns-mmddk-midiopendesc). There are two other structures used by MIDI output device drivers and they are discussed in the Windows SDK. For more information about these structures, see [MIDIHDR](/windows/win32/api/mmeapi/ns-mmeapi-midihdr) and [MIDIOUTCAPS](/windows/win32/api/mmeapi/ns-mmeapi-midioutcaps). The following is a list of the audio device messages and the **modMessage** entry-point function that processes them for a MIDI output driver: -[**modMessage**](/previous-versions/windows/hardware/drivers/ff537532(v=vs.85)) +[**modMessage**](mod-message.md) -[**MODM\_CACHEDRUMPATCHES**](/previous-versions/windows/hardware/drivers/ff537533(v=vs.85)) +[**MODM\_CACHEDRUMPATCHES**](modm-cachedrumpatches.md) -[**MODM\_CACHEPATCHES**](/previous-versions/windows/hardware/drivers/ff537534(v=vs.85)) +[**MODM\_CACHEPATCHES**](modm-cachepatches.md) -[**MODM\_DATA**](/previous-versions/windows/hardware/drivers/ff537535(v=vs.85)) +[**MODM\_DATA**](modm-data.md) -[**MODM\_GETDEVCAPS**](/previous-versions/windows/hardware/drivers/ff537536(v=vs.85)) +[**MODM\_GETDEVCAPS**](modm-getdevcaps.md) -[**MODM\_GETNUMDEVS**](/previous-versions/windows/hardware/drivers/ff537537(v=vs.85)) +[**MODM\_GETNUMDEVS**](modm-getnumdevs.md) -[**MODM\_GETPOS**](/previous-versions/windows/hardware/drivers/ff537538(v=vs.85)) +[**MODM\_GETPOS**](modm-getpos.md) -[**MODM\_GETVOLUME**](/previous-versions/windows/hardware/drivers/ff537539(v=vs.85)) +[**MODM\_GETVOLUME**](modm-getvolume.md) -[**MODM\_LONGDATA**](/previous-versions/windows/hardware/drivers/ff537540(v=vs.85)) +[**MODM\_LONGDATA**](modm-longdata.md) -[**MODM\_OPEN**](/previous-versions/windows/hardware/drivers/ff537541(v=vs.85)) +[**MODM\_OPEN**](modm-open.md) -[**MODM\_PAUSE**](/previous-versions/windows/hardware/drivers/ff537542(v=vs.85)) +[**MODM\_PAUSE**](modm-pause.md) -[**MODM\_PREPARE**](/previous-versions/windows/hardware/drivers/ff537543(v=vs.85)) +[**MODM\_PREPARE**](modm-prepare.md) -[**MODM\_PROPERTIES**](/previous-versions/windows/hardware/drivers/ff537544(v=vs.85)) +[**MODM\_PROPERTIES**](modm-properties.md) -[**MODM\_RESET**](/previous-versions/windows/hardware/drivers/ff537545(v=vs.85)) +[**MODM\_RESET**](modm-reset.md) -[**MODM\_RESTART**](/previous-versions/windows/hardware/drivers/ff537546(v=vs.85)) +[**MODM\_RESTART**](modm-restart.md) -[**MODM\_SETVOLUME**](/previous-versions/windows/hardware/drivers/ff537547(v=vs.85)) +[**MODM\_SETVOLUME**](modm-setvolume.md) -[**MODM\_STOP**](/previous-versions/windows/hardware/drivers/ff537548(v=vs.85)) +[**MODM\_STOP**](modm-stop.md) -[**MODM\_STRMDATA**](/previous-versions/windows/hardware/drivers/ff537549(v=vs.85)) +[**MODM\_STRMDATA**](modm-strmdata.md) -[**MODM\_UNPREPARE**](/previous-versions/windows/hardware/drivers/ff537550(v=vs.85)) +[**MODM\_UNPREPARE**](modm-unprepare.md) -[**MOM\_CLOSE**](/previous-versions/windows/hardware/drivers/ff537551(v=vs.85)) +[**MOM\_CLOSE**](mom-close.md) -[**MOM\_DONE**](/previous-versions/windows/hardware/drivers/ff537552(v=vs.85)) - -[**MOM\_OPEN**](/previous-versions/windows/hardware/drivers/ff537553(v=vs.85)) - - +[**MOM\_DONE**](mom-done.md) +[**MOM\_OPEN**](mom-open.md) diff --git a/windows-driver-docs-pr/audio/audio-devices-troubleshooting.md b/windows-driver-docs-pr/audio/audio-devices-troubleshooting.md index f49fd13409..341ec02b3f 100644 --- a/windows-driver-docs-pr/audio/audio-devices-troubleshooting.md +++ b/windows-driver-docs-pr/audio/audio-devices-troubleshooting.md @@ -1,19 +1,19 @@ --- -title: Audio Devices Troubleshooting -description: Audio Devices Troubleshooting -ms.date: 12/19/2019 +title: Audio devices troubleshooting overview +description: This section provides information on troubleshooting device drivers for device driver developers. +ms.date: 10/28/2022 --- -# Audio Devices Troubleshooting +# Audio devices troubleshooting overview This section provides information on troubleshooting device drivers for device driver developers. -## Collecting Audio Driver Logs +## Collecting audio driver logs -To collect audio logs follow the steps outlined in [this blog entry](https://matthewvaneerde.wordpress.com/2016/09/26/report-problems-with-logs-and-suggest-features-with-the-feedback-hub/). +To collect audio logs, follow the steps outlined in [Report problems, with logs, and suggest features, with the Feedback Hub](https://matthewvaneerde.wordpress.com/2016/09/26/report-problems-with-logs-and-suggest-features-with-the-feedback-hub/) on Matthew van Eerde's blog. For general information on working with TMF files, see [Displaying a Trace Log with a TMF File](../devtest/displaying-a-trace-log-with-a-tmf-file.md). -## Troubleshooting Topics +## See also -[USB Audio Not Playing ](usb-audio-not-playing.md) +- [USB audio device not playing](usb-audio-not-playing.md) diff --git a/windows-driver-docs-pr/audio/audio-drivers-enumerations.md b/windows-driver-docs-pr/audio/audio-drivers-enumerations.md index bc4f79a956..0d586c24f8 100644 --- a/windows-driver-docs-pr/audio/audio-drivers-enumerations.md +++ b/windows-driver-docs-pr/audio/audio-drivers-enumerations.md @@ -1,9 +1,11 @@ --- title: Audio Drivers Enumerations description: This section describes the enumerations that are used by various audio properties and structures. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # Audio Drivers Enumerations diff --git a/windows-driver-docs-pr/audio/audio-drivers-event-sets.md b/windows-driver-docs-pr/audio/audio-drivers-event-sets.md index d6ac716878..819d9e29d7 100644 --- a/windows-driver-docs-pr/audio/audio-drivers-event-sets.md +++ b/windows-driver-docs-pr/audio/audio-drivers-event-sets.md @@ -1,9 +1,11 @@ --- title: Audio Drivers Event Sets description: Learn about audio drivers event sets, such as 'KSEVENTSETID\_AudioControlChange' and 'KSEVENTSETID\_LoopedStreaming'. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # Audio Drivers Event Sets diff --git a/windows-driver-docs-pr/audio/audio-drivers-interfaces.md b/windows-driver-docs-pr/audio/audio-drivers-interfaces.md index efacff5965..aa7351426f 100644 --- a/windows-driver-docs-pr/audio/audio-drivers-interfaces.md +++ b/windows-driver-docs-pr/audio/audio-drivers-interfaces.md @@ -1,9 +1,11 @@ --- title: Audio Drivers Interfaces description: Audio Drivers Interfaces -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # Audio Drivers Interfaces In Windows Vista and later Windows operating systems, digital signal processing is referred to as System Effects Audio Processing. This processing is performed by user-mode in-process COM components known as System Effects Audio Processing Objects (sAPOs). diff --git a/windows-driver-docs-pr/audio/audio-drivers-property-sets.md b/windows-driver-docs-pr/audio/audio-drivers-property-sets.md index c1c354d6d2..cfb40f12e7 100644 --- a/windows-driver-docs-pr/audio/audio-drivers-property-sets.md +++ b/windows-driver-docs-pr/audio/audio-drivers-property-sets.md @@ -1,9 +1,11 @@ --- title: Audio Drivers Property Sets description: Audio Drivers Property Sets -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # Audio Drivers Property Sets diff --git a/windows-driver-docs-pr/audio/audio-endpoint-container-id.md b/windows-driver-docs-pr/audio/audio-endpoint-container-id.md index af2d5c968c..5f686cda31 100644 --- a/windows-driver-docs-pr/audio/audio-endpoint-container-id.md +++ b/windows-driver-docs-pr/audio/audio-endpoint-container-id.md @@ -1,23 +1,23 @@ --- -title: Audio Endpoint Container ID -description: The Audio Endpoint Container ID topic discusses the reliable methods available for obtaining the container ID of an audio endpoint associated with a Bluetooth audio device. +title: Audio endpoint container ID +description: Learn about reliable methods for obtaining the container ID of an audio endpoint associated with a Bluetooth audio device ms.date: 04/20/2017 --- -# Audio Endpoint Container ID +# Audio endpoint container ID +This article discusses reliable methods for obtaining the container ID of an audio endpoint associated with a Bluetooth audio device. -The Audio Endpoint Container ID topic discusses the reliable methods available for obtaining the container ID of an audio endpoint associated with a Bluetooth audio device. +The audio endpoint builder uses an enumeration algorithm to determine the container IDs of audio endpoints and stores these IDs as properties in the MMDEVAPI endpoint property store. In certain cases, the logic used by the endpoint builder is insufficient for handling Bluetooth I2S designs where the container ID of an audio endpoint exposed by the audio driver is determined by another enumerator — the Bluetooth enumerator. -The audio endpoint builder uses an enumeration algorithm to determine the container IDs of audio endpoints, and then stores these IDs as properties in the MMDEVAPI endpoint property store. In certain cases, the logic used by the endpoint builder is not sufficient to handle Bluetooth I2S designs where the container ID of an audio endpoint exposed by the audio driver is determined by another enumerator - the Bluetooth enumerator. +This scenario involving a Bluetooth I2S design that uses its own Bluetooth enumerator is rare. However, you can develop your audio driver to provide support for such a scenario. In this case, your audio driver can support a new container ID property for endpoints. The new property is [**KSPROPERTY_JACK_CONTAINERID**](./ksproperty-jack-containerid.md) and it has been added to the existing [KSPROPSETID_Jack](./kspropsetid-jack.md) property set. The value is a GUID, which is the data type for a container ID. -This scenario involving a Bluetooth I2S design that uses its own Bluetooth enumerator is rare. But regardless, you can develop your audio driver to provide support for such a scenario. In this case, your audio driver can support a new container ID property for endpoints. The new property is [**KSPROPERTY\_JACK\_CONTAINERID**](./ksproperty-jack-containerid.md) and it's been added to the existing [KSPROPSETID\_Jack](./kspropsetid-jack.md) property set. The value is a GUID, which is the data type for a container ID. +An audio driver supports **KSPROPERTY_JACK_CONTAINERID** if, and only if, it can reliably obtain the correct container ID through other means, such as from a Bluetooth enumerator. -An audio driver supports **KSPROPERTY\_JACK\_CONTAINERID**, if and only if, it can reliably obtain the correct container ID through some other means; For example, from a Bluetooth enumerator. +If your audio driver supports the **KSPROPERTY_JACK_CONTAINERID** property, the audio system reads this property's value from the driver and stores the value as the container ID for the audio endpoint. -If your audio driver supports the **KSPROPERTY\_JACK\_CONTAINERID** property, the audio system reads this property's value from the driver, and then stores the value as the container ID for the audio endpoint. +For more information about container IDs and the algorithm mentioned earlier, see [Container ID](../install/container-ids.md) and [Audio endpoint builder algorithm](audio-endpoint-builder-algorithm.md). -For more information about container IDs and about the algorithm mentioned in the preceding section, see [Container ID](../install/container-ids.md) and [Audio Endpoint Builder Algorithm](audio-endpoint-builder-algorithm.md). +## Related topics -## Related topics -[Theory of Operation](theory-of-operation.md) +[Theory of Bluetooth bypass audio streaming](theory-of-operation.md) \ No newline at end of file diff --git a/windows-driver-docs-pr/audio/audio-helper-object-interfaces.md b/windows-driver-docs-pr/audio/audio-helper-object-interfaces.md index e8c0746367..abed6520cd 100644 --- a/windows-driver-docs-pr/audio/audio-helper-object-interfaces.md +++ b/windows-driver-docs-pr/audio/audio-helper-object-interfaces.md @@ -1,9 +1,11 @@ --- title: Audio Helper Object Interfaces description: Audio Helper Object Interfaces -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # Audio Helper Object Interfaces diff --git a/windows-driver-docs-pr/audio/audio-miniport-auxiliary-interfaces.md b/windows-driver-docs-pr/audio/audio-miniport-auxiliary-interfaces.md index 4714c99a0d..932089c533 100644 --- a/windows-driver-docs-pr/audio/audio-miniport-auxiliary-interfaces.md +++ b/windows-driver-docs-pr/audio/audio-miniport-auxiliary-interfaces.md @@ -1,9 +1,11 @@ --- title: Audio Miniport Auxiliary Interfaces description: Audio Miniport Auxiliary Interfaces -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # Audio Miniport Auxiliary Interfaces diff --git a/windows-driver-docs-pr/audio/audio-miniport-object-interfaces.md b/windows-driver-docs-pr/audio/audio-miniport-object-interfaces.md index ee4398c5c1..5f0c88ae2c 100644 --- a/windows-driver-docs-pr/audio/audio-miniport-object-interfaces.md +++ b/windows-driver-docs-pr/audio/audio-miniport-object-interfaces.md @@ -1,9 +1,11 @@ --- title: Audio Miniport Object Interfaces description: Audio Miniport Object Interfaces -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # Audio Miniport Object Interfaces diff --git a/windows-driver-docs-pr/audio/audio-port-class-functions.md b/windows-driver-docs-pr/audio/audio-port-class-functions.md index f6dca0ca04..23841d89ac 100644 --- a/windows-driver-docs-pr/audio/audio-port-class-functions.md +++ b/windows-driver-docs-pr/audio/audio-port-class-functions.md @@ -1,9 +1,11 @@ --- title: Audio Port Class Functions description: Audio Port Class Functions -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # Audio Port Class Functions diff --git a/windows-driver-docs-pr/audio/audio-processing-object-architecture.md b/windows-driver-docs-pr/audio/audio-processing-object-architecture.md index e47a5ecc75..887fc91a34 100644 --- a/windows-driver-docs-pr/audio/audio-processing-object-architecture.md +++ b/windows-driver-docs-pr/audio/audio-processing-object-architecture.md @@ -124,5 +124,6 @@ This diagram illustrates a DSP equipped system that implements effects in hardwa ![diagram that shows a dsp equipped system that implements effects in hardware.](images/audio-apo-dsp-equipped-system-with-hardware-effects-3.png) -## Related topics +## Related topics + [Windows Audio Processing Objects](windows-audio-processing-objects.md) diff --git a/windows-driver-docs-pr/audio/audio-processing-objects-utility-functions.md b/windows-driver-docs-pr/audio/audio-processing-objects-utility-functions.md new file mode 100644 index 0000000000..eef0f9ecf0 --- /dev/null +++ b/windows-driver-docs-pr/audio/audio-processing-objects-utility-functions.md @@ -0,0 +1,24 @@ +--- +title: Audio Processing Objects Utility Functions (Windows Drivers) +description: Learn more about the Audio Processing Objects Utility Functions. +ms.date: 03/06/2023 +ms.topic: reference +--- + +# Audio Processing Objects Utility Functions + +Audio processing objects must have real-time compatibility. This means that all buffers set aside for use by the audio processing interfaces and methods must be nonpageable. The real-time compatibility requirement also means that all code and data in the process path must also be nonpageable. + +The following utility functions allocate or release locked memory for use by the interfaces and methods that perform audio processing. + +[**AERT\_Allocate**](/windows/win32/api/baseaudioprocessingobject/nf-baseaudioprocessingobject-aert_allocate) + +[**AERT\_Free**](/windows/win32/api/baseaudioprocessingobject/nf-baseaudioprocessingobject-aert_free) + +The following utility functions are used to create media types for audio data processing. + +[**CreateAudioMediaType**](/windows/win32/api/audiomediatype/nf-audiomediatype-createaudiomediatype) + +[**CreateAudioMediaTypeFromUncompressedAudioFormat**](/windows/win32/api/audiomediatype/nf-audiomediatype-createaudiomediatypefromuncompressedaudioformat) + +For more information about the general requirements to help you develop audio processing objects, see [Design Considerations for sAPO Development](./exploring-the-windows-vista-audio-engine.md). \ No newline at end of file diff --git a/windows-driver-docs-pr/audio/audio-stream-object-interfaces.md b/windows-driver-docs-pr/audio/audio-stream-object-interfaces.md index fc67b5a36f..61df55a941 100644 --- a/windows-driver-docs-pr/audio/audio-stream-object-interfaces.md +++ b/windows-driver-docs-pr/audio/audio-stream-object-interfaces.md @@ -1,9 +1,11 @@ --- title: Audio Stream Object Interfaces description: Audio Stream Object Interfaces -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # Audio Stream Object Interfaces diff --git a/windows-driver-docs-pr/audio/audio-universal-drivers.md b/windows-driver-docs-pr/audio/audio-universal-drivers.md index c71a78addf..aad6011dc6 100644 --- a/windows-driver-docs-pr/audio/audio-universal-drivers.md +++ b/windows-driver-docs-pr/audio/audio-universal-drivers.md @@ -1,7 +1,7 @@ --- title: Universal Windows Drivers for Audio description: In Windows 10 you can write a universal audio driver that will work across many types of hardware. -ms.date: 04/07/2022 +ms.date: 08/15/2022 --- # Universal Windows Drivers for Audio @@ -91,7 +91,7 @@ A separate extension INF file is used to customize each base driver component fo An extension INF file must be a universal INF file. For more information, see [Using a Universal INF File](../install/using-a-universal-inf-file.md). -For information about adding software using INF files, see [Using a Component INF File](../install/using-a-component-inf-file.md). +For information about adding software using INF files, see [Using a Component INF File](../install/using-a-component-inf-file.md) and [DCH Design Principles and Best Practices](../develop/dch-principles-best-practices.md). ### Submitting componentized INF files @@ -99,7 +99,7 @@ APO INF packages must be submitted to the Partner Center separately from the bas ### SYSVAD componentized INF files -To see an example of componentized INF files examine the [sysvad/TabletAudioSample](https://github.com/Microsoft/Windows-driver-samples/tree/master/audio/sysvad/TabletAudioSample), on Github. +To see an example of componentized INF files examine the [sysvad/TabletAudioSample](https://github.com/Microsoft/Windows-driver-samples/tree/main/audio/sysvad/TabletAudioSample), on Github. | File name | Description | |----------------------------------------|--------------------------------------------------------------------------------| @@ -162,7 +162,7 @@ To allow the latest driver to be used, be sure and update the date and version, ### APO driver registry key -For third party-defined audio driver/APO registry keys, use HKR with the exception of HKLM\System\CurrentControlSet. +For third party-defined audio driver/APO registry keys, use HKR. ### Use a Windows Service to facilitate UWP <-> APO communication diff --git a/windows-driver-docs-pr/audio/bluetooth-bypass-ddi-reference.md b/windows-driver-docs-pr/audio/bluetooth-bypass-ddi-reference.md deleted file mode 100644 index f28ba5306d..0000000000 --- a/windows-driver-docs-pr/audio/bluetooth-bypass-ddi-reference.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Bluetooth Bypass DDI Reference -description: The Bluetooth bypass device driver interface (DDI) reference is a set of topics that show the structures and IOCTLs introduced with Windows 8.1 to provide support for a Bluetooth Hands-free profile (HFP) driver. -ms.date: 04/20/2017 ---- - -# Bluetooth Bypass DDI Reference - - -The Bluetooth bypass device driver interface (DDI) reference is a set of topics that show the structures and IOCTLs introduced with Windows 8.1 to provide support for a Bluetooth Hands-free profile (HFP) driver. - -For detailed information about the DDI members, see [Bluetooth HFP DDI Reference](./bluetooth-hfp-ddi-reference.md). - -## Related topics -[Theory of Operation](theory-of-operation.md) diff --git a/windows-driver-docs-pr/audio/bluetooth-bypass-guidelines-for-audio-drivers.md b/windows-driver-docs-pr/audio/bluetooth-bypass-guidelines-for-audio-drivers.md index b80f123740..ce8a31b3ca 100644 --- a/windows-driver-docs-pr/audio/bluetooth-bypass-guidelines-for-audio-drivers.md +++ b/windows-driver-docs-pr/audio/bluetooth-bypass-guidelines-for-audio-drivers.md @@ -1,30 +1,35 @@ --- -title: Bluetooth Bypass Guidelines for Audio Drivers -description: This topic describes how audio data can be rerouted past the Bluetooth host controller interface (HCI) to be processed in system-on-a-chip (SoC) solution. -ms.date: 04/20/2017 +title: Bluetooth HFP bypass guidelines for audio drivers +description: Learn how to reroute audio data past the Bluetooth hands-free profile (HFP) host controller interface (HCI) for processing in system-on-a-chip (SoC) solutions. +ms.date: 07/27/2023 --- -# Bluetooth Bypass Guidelines for Audio Drivers +# Bluetooth HFP bypass guidelines for audio drivers +This article presents Bluetooth hands-free profile (HFP) bypass design guidelines for audio driver developers, demonstrating how to reroute audio data past the Bluetooth host controller interface (HCI) for processing in system-on-a-chip (SoC) solutions. -The Bluetooth bypass design guidelines presented in this section show audio driver developers how audio data can be rerouted past the Bluetooth host controller interface (HCI) to be processed in system-on-a-chip (SoC) solution. +Bluetooth HFP bypass audio data streaming support was introduced in Windows 8.1. -Support for Bluetooth bypass audio data streaming was introduced with Windows 8.1. +Windows is compatible with low-power Intel-based and Arm-based SoC designs, optimized for "always on" scenarios where low battery consumption is crucial. -This section contains the following topics. +SoC architectures use the Universal Asynchronous Receiver/Transmitter (UART) transport mode to transmit data to and from the Bluetooth host controller. Since UARTs can't provide time-sensitive data transmission, a synchronous connection-oriented (SCO) bypass channel must be implemented alongside a UART. The SCO bypass channel transfers audio data via I2S or another connection between the audio codec and the Bluetooth radio, bypassing the Bluetooth HCI typically used to transmit audio data on PCs. -[Architectural Overview](btth-architectural-overview.md) +This feature offloads functionality present in Windows versions prior to 8.1. From a user perspective, there are no use case differences between Bluetooth hands-free profile (HFP) on SoC and Bluetooth HFP in Windows. -[Theory of Operation](theory-of-operation.md) +The following diagram illustrates the software and hardware components that work together to provide this support. -[Bluetooth Bypass DDI Reference](bluetooth-bypass-ddi-reference.md) +:::image type="content" source="images/btth-bypass-arch.png" alt-text="Diagram showing the software and hardware components that work together to provide Windows support for Bluetooth bypass audio streaming."::: -[Related Design Guidelines](related-design-guidelines.md) +This Windows feature doesn't support bypass audio streaming using advanced audio distribution profile (A2DP). Windows 8 provides a separate A2DP profile driver that fully supports audio functionality through the standard Bluetooth HCI without requiring additional audio drivers. - - - +## Bluetooth bypass DDI reference +The Bluetooth bypass device driver interface (DDI) reference is a set of topics that detail the structures and IOCTLs introduced in Windows 8.1 to provide support for a Bluetooth Hands-free profile (HFP) driver. +For detailed information about the DDI members, see [Bluetooth HFP DDI Reference](./bluetooth-hfp-ddi-reference.md). +## Related topics +- [Bluetooth HFP bypass guidelines for audio drivers](bluetooth-bypass-guidelines-for-audio-drivers.md) +- [Bluetooth HFP bypass audio streaming](bluetooth-hfp-bypass-audio-streaming.md) +- [Bluetooth Low Energy (LE) Audio](../bluetooth/bluetooth-low-energy-audio.md) diff --git a/windows-driver-docs-pr/audio/bluetooth-hfp-bypass-audio-streaming.md b/windows-driver-docs-pr/audio/bluetooth-hfp-bypass-audio-streaming.md new file mode 100644 index 0000000000..c942c2a2e1 --- /dev/null +++ b/windows-driver-docs-pr/audio/bluetooth-hfp-bypass-audio-streaming.md @@ -0,0 +1,45 @@ +--- +title: Bluetooth hands-free profile (HFP) bypass audio streaming +description: This article explains the operation and theory of Bluetooth hands-free profile (HFP) bypass audio streaming. +ms.date: 07/27/2023 +--- + +# Bluetooth HFP bypass audio streaming + +This article explains the operation and theory of Bluetooth hands-free profile (HFP) bypass audio streaming. + +In bypass mode, Bluetooth audio control path flows through a hardware connection other than the host controller interface (HCI), such as I2S, to the Bluetooth controller. This other hardware connection is often I2S, but can be any interface determined by the Bluetooth host controller. This connection is referred to as a "bypass" or "sideband" connection. + +While audio I/O occurs through the bypass connection, the over-the-air synchronous connection oriented (SCO) audio stream is still managed through the HCI. Windows 8 provides a Bluetooth Hands-Free Profile (HFP) driver to simplify managing the SCO connection and other aspects of the Hands-Free Profile. However, a custom audio driver controls audio data I/O between Windows and the bypass connection. + +The HFP driver and the custom control driver for audio I/O data have separate roles, requiring efficient communication between them. This communication is handled by a set of IOCTLs passed from the custom audio driver to the Windows HFP driver. + +Typically, the bypass connection is always present. The Plug and Play (PnP) service enumerates the hardware that includes this connection and loads the required audio driver. However, the audio system may or may not have any HFP headsets paired, and the bypass connection is only useful if at least one HFP headset is paired. + +For each paired HFP device, the Windows HFP driver registers and enables a device interface in the GUID_DEVINTERFACE_BLUETOOTH_HFP_SCO_HCIBYPASS interface class. The following conditions apply to HFP devices: + +- When Windows activates the HFP driver (usually during boot up), the HFP driver registers and enables an interface for each paired HFP device. +- When an HFP device is first paired with Windows already running, the HFP driver registers and enables an interface for the device. +- If there are n paired HFP devices, the Windows HFP driver registers n instances of the device interface. +- When a paired HFP device is removed, the Windows HFP driver disables the device interface. +- When Windows stops the HFP driver (usually during shutdown or reboot), the HFP driver disables the interface for each paired HFP device. +- The audio driver must handle multiple arrivals and removals of interfaces at any time, not just during startup or shutdown. + +## Managing I2S and SCO resources + +This section discusses the assumptions made in the design of Bluetooth bypass audio streaming support. + +Currently, Windows assumes there's only one Bluetooth host controller. Additionally, the Hands-Free Profile (HFP) synchronous connection-oriented (SCO) bypass support assumes there's only one bypass connection, and any channel opened through the HFP device driver interface is associated with that single connection. + +Audio drivers should arbitrate this channel and the single bypass connection for a single consumer on a first-come, first-serve basis. The simplest way to achieve this is for the driver to allow only a single filter to transition its pins to the ACQUIRE state. + +## See also + +The following topics provide more information about the connection life cycle and some design features of an HFP device and its audio driver: + +- [HFP device startup](startup.md) +- [HFP device connection](hfp-device-connection.md) +- [HFP device removal](removal.md) +- [Kernel streaming considerations](kernel-streaming-considerations.md) +- [Audio endpoint container ID](audio-endpoint-container-id.md) +- [Bluetooth Low Energy (LE) Audio](../bluetooth/bluetooth-low-energy-audio.md) diff --git a/windows-driver-docs-pr/audio/bluetooth-hfp-ddi-ioctls.md b/windows-driver-docs-pr/audio/bluetooth-hfp-ddi-ioctls.md index fadd84ff96..3bbb7e7f78 100644 --- a/windows-driver-docs-pr/audio/bluetooth-hfp-ddi-ioctls.md +++ b/windows-driver-docs-pr/audio/bluetooth-hfp-ddi-ioctls.md @@ -1,21 +1,21 @@ --- title: Bluetooth HFP DDI IOCTLs description: Windows 8 introduces a set of I/O control codes (IOCTLs) as part of a DDI that allows the audio driver to work with the Hands-free profile (HFP) class driver, to operate a Bluetooth audio bypass connection. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- # Bluetooth HFP DDI IOCTLs - Windows 8 introduces a set of I/O control codes (IOCTLs) as part of a DDI that allows the audio driver to work with the Hands-free profile (HFP) class driver, to operate a Bluetooth audio bypass connection. Unless otherwise stated, the following is true for all the IOCTLs in this section: -- If the request is successful, the Information member of the STATUS\_BLOCK structure is set to the size, in bytes, of the output buffer. Otherwise, the Information member is set to zero. The Status member is set to an NTSTATUS value. +- If the request is successful, the Information member of the STATUS\_BLOCK structure is set to the size, in bytes, of the output buffer. Otherwise, the Information member is set to zero. The Status member is set to an NTSTATUS value. -- All IOCTLS require IRQL <= PASSIVE\_LEVEL. +- All IOCTLS require IRQL <= PASSIVE\_LEVEL. -- The audio driver should use the IOCTLs with the IRP\_MJ\_DEVICE\_CONTROL request. +- The audio driver should use the IOCTLs with the IRP\_MJ\_DEVICE\_CONTROL request. For most of the IOCTL function codes, the audio driver must initialize the FileObject pointer in the IO\_STACK\_LOCATION for the HFP driver when the audio driver initializes a device control IRP to send to the HFP driver. The audio driver typically retrieves the file object pointer by calling IoGetDeviceObjectPointer. @@ -63,10 +63,6 @@ Windows 10 has updated the set of IOCTLs by adding the following new one: For information about the structures that work with these IOCTLs, see [Bluetooth HFP DDI Structures](bluetooth-hfp-ddi-structures.md). -## Related topics - +## Related topics [Bluetooth HFP DDI Structures](bluetooth-hfp-ddi-structures.md) - - - diff --git a/windows-driver-docs-pr/audio/bluetooth-hfp-ddi-reference.md b/windows-driver-docs-pr/audio/bluetooth-hfp-ddi-reference.md index 80d3fae452..14f67a2400 100644 --- a/windows-driver-docs-pr/audio/bluetooth-hfp-ddi-reference.md +++ b/windows-driver-docs-pr/audio/bluetooth-hfp-ddi-reference.md @@ -1,9 +1,11 @@ --- title: Bluetooth HFP DDI Reference description: Windows 8 has introduced the GUID\_DEVINTERFACE\_BLUETOOTH\_HFP\_SCO\_HCIBYPASS class, with interfaces that implement I/O control codes (IOCTLs) and structures for the Hands-free profile (HFP) bypass audio driver. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # Bluetooth HFP DDI Reference diff --git a/windows-driver-docs-pr/audio/bluetooth-hfp-ddi-structures.md b/windows-driver-docs-pr/audio/bluetooth-hfp-ddi-structures.md index a37ba7ebb0..6b1b326159 100644 --- a/windows-driver-docs-pr/audio/bluetooth-hfp-ddi-structures.md +++ b/windows-driver-docs-pr/audio/bluetooth-hfp-ddi-structures.md @@ -1,9 +1,11 @@ --- title: Bluetooth HFP DDI Structures description: This section describes the structures that work with the Windows Bluetooth Handsfree profile (HFP) driver. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # Bluetooth HFP DDI Structures @@ -17,7 +19,7 @@ This section describes the structures that work with the Windows Bluetooth Hands [**HFP\_BYPASS\_CODEC\_ID\_V1**](/windows-hardware/drivers/ddi/bthhfpddi/ns-bthhfpddi-_hfp_bypass_codec_id_v1) -## Related topics +## Related topics [Bluetooth HFP DDI Reference](bluetooth-hfp-ddi-reference.md) diff --git a/windows-driver-docs-pr/audio/btth-architectural-overview.md b/windows-driver-docs-pr/audio/btth-architectural-overview.md deleted file mode 100644 index 203690e575..0000000000 --- a/windows-driver-docs-pr/audio/btth-architectural-overview.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Windows Bluetooth host controller interface (HCI) Architectural Overview -description: This topic presents an architectural overview of the Windows 8.1 support for rerouting audio data to bypass the Bluetooth host controller interface (HCI). -ms.date: 10/22/2018 ---- - -# Windows Bluetooth host controller interface (HCI) Architectural Overview - - -This topic presents an architectural overview of the Windows 8.1 support for rerouting audio data to bypass the Bluetooth host controller interface (HCI). - -Starting with Windows 8.1, the Microsoft operating system has been updated to be compatible with low power system-on-a-chip (SoC) design solutions. The new Windows support is compatible with either Intel-based or Arm-based SoC designs. These new low-power devices will be optimized for “always on” scenarios, so low battery consumption will be a key factor for success. - -SoC architectures use the Universal Asynchronous Receiver/Transmitter (UART) transport mode to transmit data to and from the Bluetooth host controller. - -Because UARTs cannot provide time sensitive data transmission, a synchronous connection oriented (SCO) bypass channel must be implemented in addition to a UART, to transfer audio data via I2S or some other connection between the audio codec and the Bluetooth radio. This means that audio data must be rerouted to bypass the Bluetooth HCI. The Bluetooth HCI which would normally be used on PCs to transmit audio data. - -It is important to note that this feature is simply offloading the same functionality that exists in versions of Windows prior to Windows 8.1, so from a user perspective there are no use cases that are different between the Bluetooth hands-free profile (HFP) on SoC and Bluetooth HFP in Windows on a PC or laptop. - -The following diagram shows the software and hardware components that work together to provide this new support in Windows 8.1. - -![diagram showing the software and hardware components that work together to provide windows support for bluetooth bypass audio streaming.](images/btth-bypass-arch.png) - -Note that this Windows feature does not support bypass audio streaming using advanced audio distribution profile (A2DP). Windows 8 provides a separate A2DP profile driver that completely supports audio functionality through the standard Bluetooth HCI without requiring any additional audio drivers. - - - - - - - - diff --git a/windows-driver-docs-pr/audio/combine-custom-and-windows-apos.md b/windows-driver-docs-pr/audio/combine-custom-and-windows-apos.md index 01c3970fb5..496d4d409b 100644 --- a/windows-driver-docs-pr/audio/combine-custom-and-windows-apos.md +++ b/windows-driver-docs-pr/audio/combine-custom-and-windows-apos.md @@ -60,7 +60,7 @@ A custom APO must initialize the Window APO by calling its [IAudioSystemEffects: If the custom APO replaces a feature, it is generally advisable to turn off the corresponding feature on the APO. However, turning off the feature might not be strictly necessary, depending on how the feature works. To turn off a feature, query the APO for its IPropertyStore interface and call [IPropertyStore::SetValue](/windows/win32/api/propsys/nf-propsys-ipropertystore-setvalue). The properties that are supported by the APO's property store are described in "Supported IPropertyStore Properties." later in this topic. For examples of how to communicate with the Windows custom audio system effects APO property store, see the samples on Github at: -https://github.com/microsoft/Windows-driver-samples/tree/master/audio/sysvad/APO +https://github.com/Microsoft/Windows-driver-samples/tree/main/audio/sysvad/APO ### Query APO's feature state @@ -125,7 +125,7 @@ To use the APO CLSID and property key definitions, include wmcodecdsp.h and link ### APO samples There are four sample audio system effects samples. The APO samples are available on Github at: -https://github.com/microsoft/Windows-driver-samples/tree/master/audio/sysvad/APO +https://github.com/Microsoft/Windows-driver-samples/tree/main/audio/sysvad/APO ## General guidelines for custom audio system effects diff --git a/windows-driver-docs-pr/audio/customizing-default-audio-volume-settings.md b/windows-driver-docs-pr/audio/customizing-default-audio-volume-settings.md index 662d416a1e..03e2113ae7 100644 --- a/windows-driver-docs-pr/audio/customizing-default-audio-volume-settings.md +++ b/windows-driver-docs-pr/audio/customizing-default-audio-volume-settings.md @@ -7,51 +7,49 @@ keywords: - adapter drivers WDK audio , volume settings - customize audio volume settings - Port Class audio adapters WDK , volume settings -ms.date: 04/20/2017 +ms.date: 05/05/2023 --- # Customizing HD Audio Driver Volume Settings - The ability to customize the in box HD audio default audio volume and microphone boost levels to suit a specific PC, provides OEMs with some flexibility in their audio adapter installation parameters. -**Note**  The process described here can only be used if the default Microsoft HD Audio driver is being used. - - +> [!NOTE] +> The process described here can only be used if the default Microsoft HD Audio driver is being used. -By default, the HD Audio class function driver sets the audio volume and the microphone boost levels at predetermined values to ensure a pleasant “out of the box” experience for the user. +By default, the HD Audio class function driver sets the audio volume and the microphone boost levels at predetermined values to ensure a pleasant "out of the box" experience for the user. -The HD Audio class function driver, which I shall now refer to as the Audio Class driver, uses various hard-coded default values that cannot be customized for any particular PC. As such, OEMs are not able to override these values to meet their own requirements. And one of the most important settings to adjust is the volume level, as users are sensitive to the loudness or quietness of their audio systems, especially during first-time use. +The HD Audio class function driver, which is referred to here as the Audio Class driver, uses various hard-coded default values that can't be customized for any particular PC. As such, OEMs aren't able to override these values to meet their own requirements. And one of the most important settings to adjust is the volume level, as users are sensitive to the loudness or quietness of their audio systems, especially during first-time use. -The Audio Class driver has been redesigned to allow you to override the hard-coded default values. The mechanism for overriding the Audio Class driver’s hard-coded values involves writing an INF file that wraps the Audio Class driver’s inbox INF file (hdaudio.inf), and using this wrapper INF to specify the desired values. +The Audio Class driver has been redesigned to allow you to override the hard-coded default values. The mechanism for overriding the Audio Class driver's hard-coded values involves writing an INF file that wraps the Audio Class driver's inbox INF file (hdaudio.inf), and using this wrapper INF to specify the desired values. -The following diagram which shows a sample HD Audio codec topology. Note that there are IDs for the individual nodes, as well as IDs for the pin complexes.![sample audio codec topology showing pin complexes that represent the physical connectors. the mic and line input nodes, and the speaker output node show pin complex ids.](images/pin-complexid2.png) +The following diagram shows a sample HD Audio codec topology. There are IDs for the individual nodes, and IDs for the pin complexes.![sample audio codec topology showing pin complexes that represent the physical connectors. the mic and line input nodes, and the speaker output node show pin complex ids.](images/pin-complexid2.png) -The pin complexes represent the physical connectors for the associated device (e.g. speaker, mic, or line). +The pin complexes represent the physical connectors for the associated device (for example, speaker, mic, or line). To specify a custom audio volume level or microphone boost level, use the wrapper INF file to specify custom levels per pin complex ID. The levels are expressed as DWORDs that represent the default kernel streaming (KS) decibel levels that the class driver should return. -When the HD Audio class driver receives a GET request for KSPROPERTY\_AUDIO\_VOLUMELEVEL, the driver determines whether or not there is a default volume (or Mic boost) value in the registry for the path that contains the node that received the request. If there is a value in the registry, but there is no previously cached value, the default value in the registry will be applied to the device, and also returned in the KSPROPERTY\_AUDIO\_VOLUMELEVEL response. If there is no value in the registry, the HD Audio class driver retrieves a default value from the sub-device graph implementation. +When the HD Audio class driver receives a GET request for KSPROPERTY_AUDIO_VOLUMELEVEL, the driver determines whether or not there's a default volume (or Mic boost) value in the registry for the path that contains the node that received the request. If there's a value in the registry, but there's no previously cached value, the default value in the registry will be applied to the device, and also returned in the KSPROPERTY_AUDIO_VOLUMELEVEL response. If there's no value in the registry, the HD Audio class driver retrieves a default value from the sub-device graph implementation. Starting with Windows Vista, the default values are as follows: -- Endpoint volume defaults to max minus 6 dB for all device types. +- Endpoint volume defaults to max minus 6 dB for all device types. -- Microphone boost defaults to 0 dB. +- Microphone boost defaults to 0 dB. -The following steps summarize the algorithm that is used by the Audio Class driver to determine the default values to return in response to a GET request for KSPROPERTY\_AUDIO\_VOLUMELEVEL: +The following steps summarize the algorithm that is used by the Audio Class driver to determine the default values to return in response to a GET request for KSPROPERTY_AUDIO_VOLUMELEVEL: 1. Determine the pin complex at which the path containing the queried volume node terminates. -2. Perform a registry lookup to see if a volume or microphone boost default value has been provided for the pin complex found in step 1. +1. Perform a registry lookup to see if a volume or microphone boost default value has been provided for the pin complex found in step 1. -3. If a value is found in the registry, then the driver sets that value to the minimum, if it falls below the minimum value supported by the amplifier. Otherwise the value is set to the maximum, if it falls above the maximum value supported by the amplifier. If the value found in the registry is within the range supported by the amplifier, then the value is returned in response to the GET request. In addition, the driver programs the associated HD Audio amplifier widget with this value when rendering to or capturing from the pin complex. +1. If a value is found in the registry, then the driver sets that value to the minimum, if it falls below the minimum value supported by the amplifier. Otherwise the value is set to the maximum, if it falls above the maximum value supported by the amplifier. If the value found in the registry is within the range supported by the amplifier, then the value is returned in response to the GET request. In addition, the driver programs the associated HD Audio amplifier widget with this value when rendering to or capturing from the pin complex. The following folder tree shows the layout for the driver instance key that holds the default values. <Driver Key> DefaultVolumeLevels -Pin Complex (2 digit HEX, not preceded by “0x”) +Pin Complex (2 digit HEX, not preceded by "0x") Volume (DWORD in KS DB steps) Boost (DWORD in KS DB steps) @@ -62,7 +60,7 @@ The KS DB stepping values are defined as follows: +2147483647 is +32767.99998474 decibels (gain) -For more information on the unit of measurement that is used (1/65536 dB), see [**KSPROPERTY\_AUDIO\_VOLUMELEVEL**](./ksproperty-audio-volumelevel.md). +For more information on the unit of measurement that is used (1/65536 dB), see [**KSPROPERTY_AUDIO_VOLUMELEVEL**](./ksproperty-audio-volumelevel.md). To override the wdmudio.inf file, use the Include and Needs directives as shown in this code segment from the *Microsoft Virtual Audio Device Driver Sample* available as part of the [Windows Driver Kit (WDK) 8.1 Samples](https://github.com/microsoftarchive/msdn-code-gallery-microsoft/tree/master/Official%20Windows%20Driver%20Kit%20Sample/Windows%20Driver%20Kit%20(WDK)%208.1%20Samples). @@ -80,7 +78,7 @@ For more information about the Include and Needs directives, see [**INF DDInstal The following is a sample INF wrapper that wraps the INF file for the Audio Class driver. -```text +```inf ;Copyright (c) Microsoft Corporation. All rights reserved. ; ;Module Name: @@ -97,6 +95,7 @@ ClassGuid={4d36e96c-e325-11ce-bfc1-08002be10318} Provider=Microsoft DriverVer=07/28/2012,6.2.9201.0 CatalogFile=hdaudvol.cat +PnpLockdown=1 [Manufacturer] Microsoft = Microsoft,ntamd64,ntarm @@ -147,14 +146,10 @@ HKR,DefaultVolumeLevels\18,Boost,1,00,00,0A,00 ; Set to 0x000A0000 to set to 10d HdAudModel_DefaultVolume_DeviceDesc = "High Definition Audio Device" ``` -Because an HKR relative path is specified, the exact driver registry path will be determined based on the specific INF file section that is used. For more information about HKR relative paths, see [**INF AddReg Directive (Windows Drivers)**](../install/inf-addreg-directive.md). The following two registry paths are examples, your registry path will likely be different. - -HKEY\_LOCAL\_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\Class\\{4d36e96c-e325-11ce-bfc1-08002be10318}\\0002 +Because an HKR relative path is specified, the exact driver registry path will be determined based on the specific INF file section that is used. For more information about HKR relative paths, see [**INF AddReg Directive (Windows Drivers)**](../install/inf-addreg-directive.md). -- or - +## Related articles -HKEY\_LOCAL\_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\Class\\{4d36e96c-e325-11ce-bfc1-08002be10318}\\0002\\DeviceInterfaces\\eAuxIn +[Default Audio Volume Settings](default-audio-volume-settings.md) -## Related topics -[Default Audio Volume Settings](default-audio-volume-settings.md) -[**KSPROPERTY\_AUDIO\_VOLUMELEVEL**](./ksproperty-audio-volumelevel.md) +[**KSPROPERTY_AUDIO_VOLUMELEVEL**](./ksproperty-audio-volumelevel.md) diff --git a/windows-driver-docs-pr/audio/default-audio-endpoint-selection.md b/windows-driver-docs-pr/audio/default-audio-endpoint-selection.md index 0f5edf8fec..763fa271ad 100644 --- a/windows-driver-docs-pr/audio/default-audio-endpoint-selection.md +++ b/windows-driver-docs-pr/audio/default-audio-endpoint-selection.md @@ -3,7 +3,7 @@ title: Default Audio Endpoint Selection description: Default Audio Endpoint Selection keywords: - audio default endpoint selection -ms.date: 05/20/2021 +ms.date: 01/04/2023 --- # Default Audio Endpoint Selection Starting in Windows 10 @@ -205,7 +205,7 @@ The Windows 10 default audio endpoint heuristic weights each endpoint factor. Th In addition, the Windows 10 heuristic assigns a rank value (_nRankXxx_ in this topic) to each enum value within a factor category. This rank value establishes the relative importance among all enum values under the same factor. -These _WeightFactor\_Xxx_ and _nRankXxx_ values are stored in the registry during operating system installation. Registry storage makes it easier for OEMs to customize the default audio endpoint's selection process. The set of parameters for the heuristic's rank calculation depends on the endpoint's characteristics. The following table shows an example set of parameters. +These _WeightFactor\_Xxx_ and _nRankXxx_ values are stored by Windows in the registry during operating system installation. The set of parameters for the heuristic's rank calculation depends on the endpoint's characteristics. The following table shows an example set of parameters. | **Weight of endpoint factor** | **Rank value of endpoint factor** | | --- | --- | @@ -247,7 +247,7 @@ Windows 10 ships with settings that are based on the heuristic details in this t ### Inbox Heuristic Settings for the Default Console Audio Endpoint -This section describes the default heuristic settings for each factor for a console audio endpoint. The factors are listed in priority order; that is, Windows 10 gives highest priority to the first factor in the following list when the audio subsystem determines the default console endpoint. NOTE: These values may change in the future, the registry keys are the definitive source for information on the current values. +This section describes the default heuristic settings for each factor for a console audio endpoint. The factors are listed in priority order; that is, Windows 10 gives highest priority to the first factor in the following list when the audio subsystem determines the default console endpoint. #### Jack Detection Capability @@ -404,7 +404,7 @@ Windows 10 ranks the enum values for general location in the following priority - Internal - Others (treated with the same lowest priority; that is, _nRankGenLoc_ is equal to zero) -Audio drivers report the general location infomation of their endpoints through the KSPROPERTY\_JACK\_DESCRIPTION property. For details, see "Jack Description Property **"** on the MSDN Web site. +Audio drivers report the general location infomation of their endpoints through the KSPROPERTY\_JACK\_DESCRIPTION property. For more information, see [Jack Description Property](jack-description-property.md). #### Geometric Location @@ -413,7 +413,7 @@ Windows 10 ranks the enum values for geometric location in the following priorit - Front and InsideMobileLid - Others (treated with the same lowest priority; that is, with _nRankGeoLoc_ equal to zero) -Audio drivers report the geometric location information of their endpoints through the KSPROPERTY\_JACK\_DESCRIPTION property. For details, see "Jack Description Property" on the MSDN Web site. +Audio drivers report the geometric location information of their endpoints through the KSPROPERTY\_JACK\_DESCRIPTION property. For more information, see [Jack Description Property](jack-description-property.md). #### Exceptions @@ -439,16 +439,15 @@ The second exception avoids endpoints which are obvious console-oriented endpoin At the time of this writing, a third exception exists to prefer cellular audio endpoints. This exception exists only for mobile scenarios with cellular capability and is outside of the scope of this documentation. As this type of endpoint will only exist on mobile systems, this exception can safely be ignored. -## Windows 10 OEM Heuristics Customization - -All heuristic settings are controlled through registry settings. Windows 10 is shipped with the inbox default audio endpoint selection behavior. You can customize your systems to meet specific market needs. - ## See also [Jack Description Property](jack-description-property.md) [KSPROPERTY\_JACK\_DESCRIPTION2](ksproperty-jack-description2.md) +[KSPROPERTY_JACK_DESCRIPTION3](ksproperty-jack-description3.md) + [Pin Category Property](pin-category-property.md) [SetupPreferredAudioDevices](setuppreferredaudiodevices.md) + diff --git a/windows-driver-docs-pr/audio/default-audio-volume-settings.md b/windows-driver-docs-pr/audio/default-audio-volume-settings.md index 89dcab9ee6..4d12a1b233 100644 --- a/windows-driver-docs-pr/audio/default-audio-volume-settings.md +++ b/windows-driver-docs-pr/audio/default-audio-volume-settings.md @@ -31,14 +31,10 @@ If the audio adapter does not have a hardware amplifier, see [Software Volume Co **Note**  If there is a hardware amplifier, then the driver sets the range and the default level via the [**KSPROPERTY\_AUDIO\_VOLUMELEVEL**](./ksproperty-audio-volumelevel.md) kernel streaming property. If there is not a hardware amplifier, Windows will create a software volume control APO. If there is a physical volume knob on an active set of speakers, it should appear to Windows as a HID control. This will function similarly to the volume up and volume down buttons on a keyboard; Windows will see the volume knob turn and will program the volume control correspondingly (whether it is a hardware or software volume.) - - Ideally, if a set of active speakers ships in the same box with the audio adapter card, the factory should adjust the volume knob on the speakers to the position that works best with the adapter's default volume setting. If the audio adapter does not have a physical volume control knob, see the [Software Volume Control Support](./software-volume-control-support.md) topic for information about the software support provided by Windows. **Note**  If the audio hardware exposes a hardware volume control (like a volume knob), then the driver sets the range and the default level via the [**KSPROPERTY\_AUDIO\_VOLUMELEVEL**](./ksproperty-audio-volumelevel.md) Kernel Streaming property. - - The following table shows the volume ranges and default volume levels for audio in the different versions of Windows. @@ -86,10 +82,10 @@ The following table shows the volume ranges and default volume levels for audio
- \*The term non-microphone describes all playback devices and recording devices other than microphones. For information about the operational characteristics of the physical volume sliders that are represented by the software volume sliders in Windows applications, see [Audio-Tapered Volume Controls](/windows/desktop/CoreAudio/audio-tapered-volume-controls). -## Related topics +## Related topics + [Customizing Default Audio Volume Settings](customizing-default-audio-volume-settings.md) diff --git a/windows-driver-docs-pr/audio/driver-implementation-details.md b/windows-driver-docs-pr/audio/driver-implementation-details.md index f9870895f2..cdd04704b2 100644 --- a/windows-driver-docs-pr/audio/driver-implementation-details.md +++ b/windows-driver-docs-pr/audio/driver-implementation-details.md @@ -1,7 +1,7 @@ --- title: Driver Implementation Details description: This topic presents the implementation details for an audio driver that is developed for an audio adapter that is capable of processing hardware-offloaded audio streams. -ms.date: 04/17/2020 +ms.date: 09/30/2022 --- # Driver Implementation Details @@ -11,14 +11,13 @@ This topic presents the implementation details for an audio driver that is devel In other words, this topic explains what Microsoft has done (starting with Windows 8) to support a driver that works with an audio adapter that is capable of processing hardware-offloaded audio. In the following sections, this topic also shows you what the driver must be capable of to support such an adapter. -## A new *Type* GUID for node descriptors +## *Type* GUID for node descriptors +If an audio adapter is capable of processing offloaded audio streams, the adapter’s audio driver exposes this capability by using a node in the KS-filter for the adapter. -If an audio adapter is capable of processing offloaded audio streams, the adapter’s audio driver exposes this capability by using a newly introduced node in the KS-filter for the adapter. +Each node in the path of the audio stream has a node descriptor, so for this node the driver must set the *Type* GUID to [**KSNODETYPE\_AUDIO\_ENGINE**](./ksnodetype-audio-engine.md). Here’s an example of how the driver could configure the node descriptor for this new node: -Each node in the path of the audio stream has a node descriptor, so for this new node the driver must set the *Type* GUID to [**KSNODETYPE\_AUDIO\_ENGINE**](./ksnodetype-audio-engine.md). Here’s an example of how the driver could configure the node descriptor for this new node: - -```ManagedCPlusPlus +```cpp typedef struct _KSNODE_DESCRIPTOR { const KSAUTOMATION_TABLE *AutomationTable; // drv specific const GUID *Type; // must be set to KSNODETYPE_AUDIO_ENGINE @@ -26,11 +25,11 @@ typedef struct _KSNODE_DESCRIPTOR { } KSNODE_DESCRIPTOR, *PKSNODE_DESCRIPTOR; ``` -If the Name GUID is set to **KSNODETYPE\_AUDIO\_ENGINE**, then you must create a default name string for this node. You then add that string to *ks.inf*, so that during installation of the driver, the string can be used to populate the HKEY\_LOCAL\_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\MediaCategories registry key. +If the Name GUID is set to **KSNODETYPE\_AUDIO\_ENGINE**, then you must create a default name string for this node. You then add that string to *ks.inf*, so that during installation of the driver, the string can be used to populate the *MediaCategories* registry key. The definition of the GUID for the new node type, **KSNODETYPE\_AUDIO\_ENGINE**, is as follows: -```ManagedCPlusPlus +```cpp Code style #define STATIC_KSNODETYPE_AUDIO_ENGINE\ 0x35caf6e4, 0xf3b3, 0x4168, 0xbb, 0x4b, 0x55, 0xe7, 0x7a, 0x46, 0x1c, 0x7e @@ -42,7 +41,7 @@ For more information, see the *ksmedia.h* header file. And based on the preceding information, a descriptor for a miniport node could look like the following: -```ManagedCPlusPlus +```cpp PCNODE_DESCRIPTOR MiniportNodes[] = { // KSNODE_WAVE_AUDIO_ENGINE @@ -55,14 +54,13 @@ PCNODE_DESCRIPTOR MiniportNodes[] = }; ``` -## A new KS property set for audio engines - +## KS property set for audio engines Starting with Windows 8, the [KSPROPSETID\_AudioEngine](./kspropsetid-audioengine.md) property set has been introduced to support hardware audio engines and hardware-offloaded audio processing. So the driver for an adapter that can process offloaded audio streams must support the properties in this new property set. The new property set, **KSPROPSETID\_AudioEngine**, is defined as follows: -```ManagedCPlusPlus +```cpp #define STATIC_KSPROPSETID_AudioEngine\ 0x3A2F82DCL, 0x886F, 0x4BAA, 0x9E, 0xB4, 0x8, 0x2B, 0x90, 0x25, 0xC5, 0x36 DEFINE_GUIDSTRUCT("3A2F82DC-886F-4BAA-9EB4-082B9025C536", KSPROPSETID_AudioEngine); @@ -94,7 +92,7 @@ Here are the new properties in the **KSPROPSETID\_AudioEngine** property set: ## Updates to the KSPROPSETID\_ Audio property set -In addition to supporting the properties in the new **KSPROPSETID\_AudioEngine** property set, the driver must also support the following existing properties in the [KSPROPSETID\_Audio](./kspropsetid-audio.md) property set: +In addition to supporting the properties in the **KSPROPSETID\_AudioEngine** property set, the driver must also support the following existing properties in the [KSPROPSETID\_Audio](./kspropsetid-audio.md) property set: [**KSPROPERTY\_AUDIO\_MUTE**](./ksproperty-audio-mute.md) @@ -102,9 +100,9 @@ In addition to supporting the properties in the new **KSPROPSETID\_AudioEngine** [**KSPROPERTY\_AUDIO\_VOLUMELEVEL**](./ksproperty-audio-volumelevel.md) -And to complete the implementation of driver support for hardware-offloaded audio processing, new properties have been added to the **KSPROPSETID\_ Audio** property set. +And to complete the implementation of driver support for hardware-offloaded audio processing, properties are available to the **KSPROPSETID\_ Audio** property set. -Here are the new **KSPROPSETID\_ Audio** properties: +Here are the **KSPROPSETID\_ Audio** properties: [**KSPROPERTY\_AUDIO\_LINEAR\_BUFFER\_POSITION**](./ksproperty-audio-linear-buffer-position.md) @@ -115,7 +113,7 @@ Here are the new **KSPROPSETID\_ Audio** properties: ## Port-class driver updates and glitch reporting -In addition to the support described in the preceding sections for hardware-offloaded audio processing, the Windows port-class driver has also been updated with "helper interfaces" to make it simple to develop a driver that can work with offloaded audio streams. And when such a driver detects glitches, there is a mechanism in place to allow the driver to report the glitch errors. The following topics provide more details about the helper interfaces and glitch reporting: +In addition to the support described in the preceding sections for hardware-offloaded audio processing, the Windows port-class driver has also includes "helper interfaces" to make it simple to develop a driver that can work with offloaded audio streams. And when such a driver detects glitches, there is a mechanism in place to allow the driver to report the glitch errors. The following topics provide more details about the helper interfaces and glitch reporting: [Helper Interfaces for Offloaded Audio Processing](helper-interfaces-for-offloaded-audio-processing.md) diff --git a/windows-driver-docs-pr/audio/drv-querydeviceinterface.md b/windows-driver-docs-pr/audio/drv-querydeviceinterface.md new file mode 100644 index 0000000000..1776bb9272 --- /dev/null +++ b/windows-driver-docs-pr/audio/drv-querydeviceinterface.md @@ -0,0 +1,87 @@ +--- +title: DRV_QUERYDEVICEINTERFACE function (Windows Drivers) +description: Learn more about the DRV_QUERYDEVICEINTERFACE function. +keywords: +- mmddk/xxxMessage +- xxxMessage +ms.date: 03/06/2023 +ms.topic: reference +--- + +# DRV\_QUERYDEVICEINTERFACE function + +The DRV\_QUERYDEVICEINTERFACE message queries for the device-interface name of a **waveIn**, **waveOut**, **midiIn**, **midiOut**, or **mixer** device. + +## Syntax + +``` c++ +DWORD xxxMessage( +  UINT      uDeviceID, +  UINT      uMsg, +  DWORD_PTR dwParam1, +  DWORD_PTR dwParam2 +); +``` + +## Parameters + +- *uDeviceID* + Specifies the ID of the target device. + +- *uMsg* + Caller sets this parameter to DRV\_QUERYDEVICEINTERFACE when it calls **xxxMessage** to process this device message. + +- *dwParam1* + Pointer to a caller-allocated buffer into which the function writes a null-terminated Unicode string containing the device-interface name. If the device has no device interface, the string length is zero. + +- *dwParam2* + Specifies the buffer size in bytes. This is an input parameter to the function. The caller should specify a size that is greater than or equal to the buffer size retrieved by the [**DRV\_QUERYDEVICEINTERFACESIZE**](drv-querydeviceinterfacesize.md) message. + +## Return value + +The *xxx*Message function returns MMSYSERR\_NOERROR if the message is handled successfully. Otherwise, it returns an appropriate error code. + +## Remarks + +The DRV\_QUERYDEVICEINTERFACE message is supported in Windows Me, and Windows 2000 and later. This message is valid only for the [**waveInMessage**](/windows/win32/api/mmeapi/nf-mmeapi-waveinmessage), [**waveOutMessage**](/windows/win32/api/mmeapi/nf-mmeapi-waveoutmessage), [**midiInMessage**](/windows/win32/api/mmeapi/nf-mmeapi-midiinmessage), [**midiOutMessage**](/windows/win32/api/mmeapi/nf-mmeapi-midioutmessage), and [**mixerMessage**](/windows/win32/api/mmeapi/nf-mmeapi-mixermessage) functions. The system intercepts this message and returns the appropriate value without sending the message to the device driver. For general information about system-intercepted **xxxMessage** functions, see [System-Intercepted Device Messages](system-intercepted-device-messages.md). + +The following two message constants are used together for the purpose of obtaining device interface names: + +- DRV\_QUERYDEVICEINTERFACESIZE + +- DRV\_QUERYDEVICEINTERFACE + +The first message obtains the size in bytes of the buffer needed to hold the string containing the device interface name. The second message retrieves the name string in a buffer of the required size. + +For more information, see [Obtaining a Device Interface Name](obtaining-a-device-interface-name.md). + +## Requirements + + + + + + + + + + + + +

Target platform

Desktop

Header

Mmddk.h (include Mmddk.h)
+ +## See also + +[**DRV\_QUERYDEVICEINTERFACESIZE**](drv-querydeviceinterfacesize.md) + +[**midiInMessage**](/windows/win32/api/mmeapi/nf-mmeapi-midiinmessage) + +[**midiOutMessage**](/windows/win32/api/mmeapi/nf-mmeapi-midioutmessage) + +[**mixerMessage**](/windows/win32/api/mmeapi/nf-mmeapi-mixermessage) + +[System-Intercepted Device Messages](system-intercepted-device-messages.md) + +[**waveInMessage**](/windows/win32/api/mmeapi/nf-mmeapi-waveinmessage) + +[**waveOutMessage**](/windows/win32/api/mmeapi/nf-mmeapi-waveoutmessage) diff --git a/windows-driver-docs-pr/audio/drv-querydeviceinterfacesize.md b/windows-driver-docs-pr/audio/drv-querydeviceinterfacesize.md new file mode 100644 index 0000000000..f402d4be3d --- /dev/null +++ b/windows-driver-docs-pr/audio/drv-querydeviceinterfacesize.md @@ -0,0 +1,87 @@ +--- +title: DRV_QUERYDEVICEINTERFACESIZE function (Windows Drivers) +description: Learn more about the DRV_QUERYDEVICEINTERFACESIZE function. +keywords: +- mmddk/xxxMessage +- xxxMessage +ms.date: 03/06/2023 +ms.topic: reference +--- + +# DRV\_QUERYDEVICEINTERFACESIZE function + +The DRV\_QUERYDEVICEINTERFACESIZE message queries for the size of the buffer required to hold the device-interface name. + +## Syntax + +``` c++ +DWORD xxxMessage( +  UINT      uDeviceID, +  UINT      uMsg, +  DWORD_PTR dwParam1, +  DWORD_PTR dwParam2 +); +``` + +## Parameters + +- *uDeviceID* + Specifies the ID of the target device. + +- *uMsg* + Caller sets this parameter to DRV\_QUERYDEVICEINTERFACESIZE when it calls **xxxMessage** to process this device message. + +- *dwParam1* + Pointer to buffer size. This parameter points to a ULONG variable into which the function writes the required buffer size in bytes. The size includes storage space for the name string's terminating null. The size is zero if the device ID identifies a device that has no device interface. + +- *dwParam2* + Unused. Set this parameter to zero. + +## Return value + +The **xxxMessage** function returns MMSYSERR\_NOERROR if the message is handled successfully. Otherwise, it returns an appropriate error code. + +## Remarks + +This message is valid only for the [**waveInMessage**](/windows/win32/api/mmeapi/nf-mmeapi-waveinmessage), [**waveOutMessage**](/windows/win32/api/mmeapi/nf-mmeapi-waveoutmessage), [**midiInMessage**](/windows/win32/api/mmeapi/nf-mmeapi-midiinmessage), [**midiOutMessage**](/windows/win32/api/mmeapi/nf-mmeapi-midioutmessage), and [**mixerMessage**](/windows/win32/api/mmeapi/nf-mmeapi-mixermessage) functions. The system intercepts this message and returns the appropriate value without sending the message to the device driver. For general information about system-intercepted **xxxMessage** functions, see [System-Intercepted Device Messages](system-intercepted-device-messages.md). + +The buffer size retrieved by this message is expressed as a byte count. It specifies the size of the buffer needed to hold the null-terminated Unicode string that contains the device-interface name. The caller allocates a buffer of the specified size and uses the [**DRV\_QUERYDEVICEINTERFACE**](drv-querydeviceinterface.md) message to retrieve the device-interface name string. + +For more information, see [Obtaining a Device Interface Name](obtaining-a-device-interface-name.md). + +## Requirements + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in Microsoft Windows Me and Windows 2000 and later operating systems.

Header

Mmddk.h (include Mmddk.h)
+ +## See also + +[**DRV\_QUERYDEVICEINTERFACE**](drv-querydeviceinterface.md) + +[**midiInMessage**](/windows/win32/api/mmeapi/nf-mmeapi-midiinmessage) + +[**midiOutMessage**](/windows/win32/api/mmeapi/nf-mmeapi-midioutmessage) + +[**mixerMessage**](/windows/win32/api/mmeapi/nf-mmeapi-mixermessage) + +[Obtaining a Device Interface Name](obtaining-a-device-interface-name.md) + +[System-Intercepted Device Messages](system-intercepted-device-messages.md) + +[**waveInMessage**](/windows/win32/api/mmeapi/nf-mmeapi-waveinmessage) + +[**waveOutMessage**](/windows/win32/api/mmeapi/nf-mmeapi-waveoutmessage) diff --git a/windows-driver-docs-pr/audio/drv-querydevnode.md b/windows-driver-docs-pr/audio/drv-querydevnode.md new file mode 100644 index 0000000000..170cb3ba4e --- /dev/null +++ b/windows-driver-docs-pr/audio/drv-querydevnode.md @@ -0,0 +1,79 @@ +--- +title: DRV_QUERYDEVNODE function (Windows Drivers) +description: Learn more about the DRV_QUERYDEVNODE function. +keywords: +- mmddk/xxxMessage +- xxxMessage +ms.date: 03/06/2023 +ms.topic: reference +--- + +# DRV\_QUERYDEVNODE function + +The DRV\_QUERYDEVNODE message queries for the [*devnode*](../debugger/-devnode.md) number assigned to the device by the Plug and Play manager. + +## Syntax + +``` c++ +DWORD xxxMessage( +  UINT      uDeviceID, +  UINT      uMsg, +  DWORD_PTR dwParam1, +  DWORD_PTR dwParam2 +); +``` + +## Parameters + +- *uDeviceID* + Specifies the ID of the target device. + +- *uMsg* + Caller sets this parameter to DRV\_QUERYDEVNODE when it calls **xxxMessage** to process this device message. + +- *dwParam1* + Pointer to a caller-allocated DWORD variable into which the function writes the devnode number. If no devnode is assigned to the device, the function sets this variable to zero. + +- *dwParam2* + Unused. Set this parameter to zero. + +## Return value + +The **xxxMessage** function returns MMSYSERR\_NOERROR if the message is handled successfully. Otherwise, it returns an appropriate error code. + +## Remarks + +In Windows 2000 and later, the message always returns MMSYSERR\_NOTSUPPORTED. This message is valid only for the [**waveInMessage**](/windows/win32/api/mmeapi/nf-mmeapi-waveinmessage), [**waveOutMessage**](/windows/win32/api/mmeapi/nf-mmeapi-waveoutmessage), [**midiInMessage**](/windows/win32/api/mmeapi/nf-mmeapi-midiinmessage), [**midiOutMessage**](/windows/win32/api/mmeapi/nf-mmeapi-midioutmessage), and [**mixerMessage**](/windows/win32/api/mmeapi/nf-mmeapi-mixermessage) functions. The system intercepts this message and returns the appropriate value without sending the message to the device driver. For general information about system-intercepted **xxxMessage** functions, see [System-Intercepted Device Messages](system-intercepted-device-messages.md). + +## Requirements + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in Microsoft Windows Me/98 and not supported Windows 2000 and later operating systems.

Header

Mmddk.h (include Mmddk.h)
+ +## See also + +[**midiInMessage**](/windows/win32/api/mmeapi/nf-mmeapi-midiinmessage) + +[**midiOutMessage**](/windows/win32/api/mmeapi/nf-mmeapi-midioutmessage) + +[**mixerMessage**](/windows/win32/api/mmeapi/nf-mmeapi-mixermessage) + +[System-Intercepted Device Messages](system-intercepted-device-messages.md) + +[**waveInMessage**](/windows/win32/api/mmeapi/nf-mmeapi-waveinmessage) + +[**waveOutMessage**](/windows/win32/api/mmeapi/nf-mmeapi-waveoutmessage) \ No newline at end of file diff --git a/windows-driver-docs-pr/audio/drv-querymappable.md b/windows-driver-docs-pr/audio/drv-querymappable.md new file mode 100644 index 0000000000..434da68c6e --- /dev/null +++ b/windows-driver-docs-pr/audio/drv-querymappable.md @@ -0,0 +1,83 @@ +--- +title: DRV_QUERYMAPPABLE function (Windows Drivers) +description: Learn more about the DRV_QUERYMAPPABLE function. +keywords: +- mmddk/xxxMessage +- xxxMessage +ms.date: 03/06/2023 +ms.topic: reference +--- + +# DRV\_QUERYMAPPABLE function + +The DRV\_QUERYMAPPABLE message queries for whether the specified device can be used by a mapper. + +## Syntax + +``` c++ +DWORD xxxMessage( +  UINT      uDeviceID, +  UINT      uMsg, +  DWORD_PTR dwParam1, +  DWORD_PTR dwParam2 +); +``` + +## Parameters + +- *uDeviceID* + Specifies the ID of the target device. + +- *uMsg* + Caller sets this parameter to DRV\_QUERYMAPPABLE when it calls **xxxMessage** to process this device message. + +- *dwParam1* + Unused. Set this parameter to zero. + +- *dwParam2* + Unused. Set this parameter to zero. + +## Return value + +The **xxxMessage** function returns MMSYSERR\_NOERROR if the device is mappable. Otherwise, it returns an appropriate error code. + +## Remarks + +This message is valid only for the [**waveInMessage**](/windows/win32/api/mmeapi/nf-mmeapi-waveinmessage), [**waveOutMessage**](/windows/win32/api/mmeapi/nf-mmeapi-waveoutmessage), [**midiInMessage**](/windows/win32/api/mmeapi/nf-mmeapi-midiinmessage), [**midiOutMessage**](/windows/win32/api/mmeapi/nf-mmeapi-midioutmessage), [**mixerMessage**](/windows/win32/api/mmeapi/nf-mmeapi-mixermessage) and [**auxOutMessage**](/windows/win32/api/mmeapi/nf-mmeapi-auxoutmessage) functions. The system intercepts this message and returns the appropriate value without sending the message to the device driver. For general information about system-intercepted **xxxMessage** functions, see [System-Intercepted Device Messages](system-intercepted-device-messages.md). + +When an application program opens a mapper instead of a specific audio device, the system inserts a mapper between the application and the available devices. The mapper selects an appropriate device by mapping the application's requirements to one of the available devices. For more information about mappers, see the Microsoft Windows SDK documentation. + +## Requirements + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in Microsoft Windows Me/98 and Windows 2000 and later operating systems.

Header

Mmddk.h (include Mmddk.h)
+ +## See also + +[**auxOutMessage**](/windows/win32/api/mmeapi/nf-mmeapi-auxoutmessage) + +[**midiInMessage**](/windows/win32/api/mmeapi/nf-mmeapi-midiinmessage) + +[**midiOutMessage**](/windows/win32/api/mmeapi/nf-mmeapi-midioutmessage) + +[**mixerMessage**](/windows/win32/api/mmeapi/nf-mmeapi-mixermessage) + +[System-Intercepted Device Messages](system-intercepted-device-messages.md) + +[**waveInMessage**](/windows/win32/api/mmeapi/nf-mmeapi-waveinmessage) + +[**waveOutMessage**](/windows/win32/api/mmeapi/nf-mmeapi-waveoutmessage) diff --git a/windows-driver-docs-pr/audio/drvm-mapper-consolevoicecom-get.md b/windows-driver-docs-pr/audio/drvm-mapper-consolevoicecom-get.md new file mode 100644 index 0000000000..58cc6f3e5f --- /dev/null +++ b/windows-driver-docs-pr/audio/drvm-mapper-consolevoicecom-get.md @@ -0,0 +1,91 @@ +--- +title: DRVM_MAPPER_CONSOLEVOICECOM_GET function (Windows Drivers) +description: Learn more about the DRVM_MAPPER_CONSOLEVOICECOM_GET function. +keywords: +- mmddk/xxxMessage +- xxxMessage +ms.date: 03/06/2023 +ms.topic: reference +--- + +# DRVM\_MAPPER\_CONSOLEVOICECOM\_GET function + +The DRVM\_MAPPER\_CONSOLEVOICECOM\_GET message retrieves the device ID of the preferred voice-communications device. + +## Syntax + +``` c++ +DWORD xxxMessage( +  UINT      uDeviceID, +  UINT      uMsg, +  DWORD_PTR dwParam1, +  DWORD_PTR dwParam2 +); +``` + +## Parameters + +- *uDeviceID* + Specifies the ID of the target device. See the following **Remarks** section for more information about how to cast this value for use with the appropriate function. + +- *uMsg* + Caller sets this parameter to DRVM\_MAPPER\_CONSOLEVOICECOM\_GET when it calls **xxxMessage** to process this device message. + +- *dwParam1* + Pointer to device ID. This parameter points to a DWORD variable into which the function writes the device ID of the current preferred voice-communications device. The function writes the value (-1) if no device is available that qualifies as a preferred voice-communications device. + +- *dwParam2* + Pointer to status flags. This parameter points to a DWORD variable into which the function writes the device-status flags. Only one flag bit is currently defined: DRVM\_MAPPER\_PREFERRED\_FLAGS\_PREFERREDONLY. For more information, see the following Remarks section. + +## Return value + +The *xxx*Message function returns MMSYSERR\_NOERROR if the message is handled successfully. Otherwise, it returns an appropriate error code. + +## Remarks + +This message is valid only for the [**waveInMessage**](/windows/win32/api/mmeapi/nf-mmeapi-waveinmessage) and [**waveOutMessage**](/windows/win32/api/mmeapi/nf-mmeapi-waveoutmessage) functions. When a caller calls these two functions with the DRVM\_MAPPER\_CONSOLEVOICECOM\_GET message, the caller must specify the device ID as WAVE\_MAPPER, and then cast this value to the appropriate handle type. For the **waveInMessage**, **waveOutMessage**, [**midiInMessage**](/windows/win32/api/mmeapi/nf-mmeapi-midiinmessage), [**midiOutMessage**](/windows/win32/api/mmeapi/nf-mmeapi-midioutmessage), or [**mixerMessage**](/windows/win32/api/mmeapi/nf-mmeapi-mixermessage) functions, the caller must cast the device ID to a handle of type HWAVEIN, HWAVEOUT, HMIDIIN, HMIDIOUT, or HMIXER, respectively. Note that if the caller supplies a valid handle instead of a device ID for this parameter, the function fails and returns error code MMSYSERR\_NOSUPPORT. + +The system intercepts this message and returns the appropriate value without sending the message to the device driver. For general information about system-intercepted **xxxMessage** functions, see [System-Intercepted Device Messages](system-intercepted-device-messages.md). + +This message provides a way to determine which device is preferred specifically for voice communications, in contrast to the [**DRVM\_MAPPER\_PREFERRED\_GET**](drvm-mapper-preferred-get.md) message, which determines which device is preferred for all other audio functions. + +For example, the preferred **waveOut** device for voice communications might be the earpiece in a headset, but the preferred **waveOut** device for all other audio functions might be a set of stereo speakers. + +When the DRVM\_MAPPER\_PREFERRED\_FLAGS\_PREFERREDONLY flag bit is set in the DWORD location pointed to by *dwParam2*, the **waveIn** and **waveOut** APIs use only the current preferred voice-communications device and do not search for other available devices if the preferred device is unavailable. The flag that is output by either the **waveInMessage** or **waveOutMessage** call applies to the preferred voice-communications device for both the **waveIn** and **waveOut** APIs, regardless of whether the call is made to **waveInMessage** or **waveOutMessage**. For more information, see [Preferred Voice-Communications Device ID](preferred-voice-communications-device-id.md). + +## Requirements + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in Microsoft Windows Me and Windows 2000 and later operating systems.

Header

Mmddk.h (include Mmddk.h)
+ +## See also + +[**DRVM\_MAPPER\_PREFERRED\_GET**](drvm-mapper-preferred-get.md) + +[**midiInMessage**](/windows/win32/api/mmeapi/nf-mmeapi-midiinmessage) + +[**midiOutMessage**](/windows/win32/api/mmeapi/nf-mmeapi-midioutmessage) + +[**mixerMessage**](/windows/win32/api/mmeapi/nf-mmeapi-mixermessage) + +[Preferred Voice-Communications Device ID](preferred-voice-communications-device-id.md) + +[System-Intercepted Device Messages](system-intercepted-device-messages.md) + +[**waveInMessage**](/windows/win32/api/mmeapi/nf-mmeapi-waveinmessage) + +[**waveOutMessage**](/windows/win32/api/mmeapi/nf-mmeapi-waveoutmessage) diff --git a/windows-driver-docs-pr/audio/drvm-mapper-preferred-get.md b/windows-driver-docs-pr/audio/drvm-mapper-preferred-get.md new file mode 100644 index 0000000000..8191757766 --- /dev/null +++ b/windows-driver-docs-pr/audio/drvm-mapper-preferred-get.md @@ -0,0 +1,93 @@ +--- +title: DRVM_MAPPER_PREFERRED_GET function (Windows Drivers) +description: Learn more about the DRVM_MAPPER_PREFERRED_GET function. +keywords: +- mmddk/xxxMessage +- xxxMessage +ms.date: 03/06/2023 +ms.topic: reference +--- + +# DRVM\_MAPPER\_PREFERRED\_GET function + +The DRVM\_MAPPER\_PREFERRED\_GET message retrieves the device ID of the preferred audio device. + +## Syntax + +``` c++ +DWORD xxxMessage( +  UINT      uDeviceID, +  UINT      uMsg, +  DWORD_PTR dwParam1, +  DWORD_PTR dwParam2 +); +``` + +## Parameters + +- *uDeviceID* + Specifies the ID of the target device. See the following **Remarks** section for more information about how to cast this value for use with the appropriate function. + +- *uMsg* + Caller sets this parameter to DRVM\_MAPPER\_PREFERRED\_GET when it calls **xxxMessage** to process this device message. + +- *dwParam1* + Pointer to device ID. This parameter points to a DWORD variable into which the function writes the device ID of the current preferred device. The function writes the value (-1) if no device is available that qualifies as a preferred device. + +- *dwParam2* + Pointer to status flags. This parameter points to a DWORD variable into which the function writes the device-status flags. Only one flag bit is currently defined (for **waveInMessage** and **waveOutMessage** calls only): DRVM\_MAPPER\_PREFERRED\_FLAGS\_PREFERREDONLY. For more information, see the following Remarks section. + +## Return value + +The *xxx*Message function returns MMSYSERR\_NOERROR if the message is handled successfully. Otherwise, it returns an appropriate error code. + +## Remarks + +This message is valid only for the [**waveInMessage**](/windows/win32/api/mmeapi/nf-mmeapi-waveinmessage), [**waveOutMessage**](/windows/win32/api/mmeapi/nf-mmeapi-waveoutmessage) and [**midiOutMessage**](/windows/win32/api/mmeapi/nf-mmeapi-midioutmessage) functions. When the caller calls these functions with the DRVM\_MAPPER\_PREFERRED\_GET message, the caller must first specify the device ID as WAVE\_MAPPER (for **waveInMessage** or **waveOutMessage**) or MIDI\_MAPPER (for **midiOutMessage**), and then cast this value to the appropriate handle type. For the **waveInMessage**, **waveOutMessage**, or **midiOutMessage** functions, the caller must cast the device ID to a handle type HWAVEIN, HWAVEOUT or HMIDIOUT, respectively. Note that if the caller supplies a valid handle instead of a device ID for this parameter, the function fails and returns error code MMSYSERR\_NOSUPPORT. + +The system intercepts this message and returns the appropriate value without sending the message to the device driver. For general information about system-intercepted **xxxMessage** functions, see [System-Intercepted Device Messages](system-intercepted-device-messages.md). + +This message provides a way to determine which device is preferred for audio functions in general, in contrast to the [**DRVM\_MAPPER\_CONSOLEVOICECOM\_GET**](drvm-mapper-consolevoicecom-get.md) message, which determines which device is preferred specifically for voice communications. + +When the DRVM\_MAPPER\_PREFERRED\_FLAGS\_PREFERREDONLY flag bit is set in the DWORD location pointed to by *dwParam2*, the **waveIn** and **waveOut** APIs use only the current preferred device and do not search for other available devices if the preferred device is unavailable. Note that the **midiOutMessage** function does not output this flag--the **midiOut** API always uses only the preferred device. The flag that is output by either the **waveInMessage** or **waveOutMessage** call applies to the preferred device for both the **waveIn** and **waveOut** APIs, regardless of whether the call is made to **waveInMessage** or **waveOutMessage**. + +The *xxx*Message functions accept this value in place of a valid device handle in order to allow an application to determine the default device ID without first having to open a device. For more information, see [Accessing the Preferred Device ID](accessing-the-preferred-device-id.md). + +## Requirements + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in Microsoft Windows Me and Windows 2000 and later operating systems.

Header

Mmddk.h (include Mmddk.h)
+ +## See also + +[**Accessing the Preferred Device ID**](accessing-the-preferred-device-id.md) + +[**DRVM\_MAPPER\_CONSOLEVOICECOM\_GET**](drvm-mapper-consolevoicecom-get.md) + +[**midiInMessage**](/windows/win32/api/mmeapi/nf-mmeapi-midiinmessage) + +[**midiOutMessage**](/windows/win32/api/mmeapi/nf-mmeapi-midioutmessage) + +[**mixerMessage**](/windows/win32/api/mmeapi/nf-mmeapi-mixermessage) + +[Preferred Voice-Communications Device ID](preferred-voice-communications-device-id.md) + +[System-Intercepted Device Messages](system-intercepted-device-messages.md) + +[**waveInMessage**](/windows/win32/api/mmeapi/nf-mmeapi-waveinmessage) + +[**waveOutMessage**](/windows/win32/api/mmeapi/nf-mmeapi-waveoutmessage) diff --git a/windows-driver-docs-pr/audio/extended-capabilities-from-a-wdm-audio-driver.md b/windows-driver-docs-pr/audio/extended-capabilities-from-a-wdm-audio-driver.md index 35c1586243..c306a670cf 100644 --- a/windows-driver-docs-pr/audio/extended-capabilities-from-a-wdm-audio-driver.md +++ b/windows-driver-docs-pr/audio/extended-capabilities-from-a-wdm-audio-driver.md @@ -8,7 +8,7 @@ keywords: - unique device IDs WDK audio - identifying audio devices - hardware-specific information WDK audio -ms.date: 04/20/2017 +ms.date: 09/29/2022 --- # Extended Capabilities from a WDM Audio Driver @@ -17,7 +17,7 @@ ms.date: 04/20/2017 ## -By handling the [**KSPROPERTY\_GENERAL\_COMPONENTID**](../stream/ksproperty-general-componentid.md) property, an audio filter can provide hardware-specific information that applications can use to uniquely identify the underlying device. Microsoft Windows XP is the first version of Windows to support this feature; this feature is not available in earlier versions. +By handling the [**KSPROPERTY\_GENERAL\_COMPONENTID**](../stream/ksproperty-general-componentid.md) property, an audio filter can provide hardware-specific information that applications can use to uniquely identify the underlying device. The filter provides the hardware-specific information in the form of a [**KSCOMPONENTID**](/windows-hardware/drivers/ddi/ks/ns-ks-kscomponentid) structure that contains the following: @@ -75,7 +75,6 @@ An application can access the data from the driver's KSCOMPONENTID structure thr - After receiving the KSCOMPONENTID structure from the filter's property handler, the WDMAud system driver (Wdmaud.sys) converts the data from this structure to the *XXX*CAPS2 format that the *xxx*GetDevCaps functions use. @@ -86,15 +85,15 @@ WDMAud concatenates the **Version** and **Revision** members from KSCOMPONENTID **vDriverVersion** = (**Version** << 8) | (**Revision** & 0xFF) -Microsoft previously required vendors to register manufacturer IDs and product IDs for their audio devices. These IDs were then released in the header file Mmreg.h. +The high-order byte is the major version number, and the low-order byte is the minor version number. -In Windows XP and later, registered IDs are no longer necessary; they are replaced by the manufacturer and product GUIDs that are provided through the KSPROPERTY\_GENERAL\_COMPONENTID property. The GUIDs are more convenient for vendors to use than registered IDs because GUIDs are inherently unique, are easily generated, and require no registration. +The manufacturer and product GUIDs that are provided through the KSPROPERTY\_GENERAL\_COMPONENTID property. The GUIDs are inherently unique, are easily generated. -However, if you have already registered product and manufacturer IDs with Microsoft (and they are in Mmreg.h), you can use the macros INIT\_MMREG\_PID and INIT\_MMREG\_MID in Ksmedia.h to convert your product and manufacturer IDs into GUIDs. If you use these macros to generate the GUIDs, WDMAud is able to recover the original product and manufacturer IDs from the GUIDs and copy these IDs into the **wPid** and **wMid** members of the capabilities structure that is filled in by the *xxx*GetDevCaps call. +Use the GuidGen utility to generate the manufacturer and product GUIDs. (GuidGen is included in the Microsoft Windows SDK.) When a driver's GUIDs are of this type, WDMAud loads default constants MM\_UNMAPPED and MM\_PID\_UNMAPPED into the **wMid** and **wPid** members, respectively, of the capabilities structure that is filled in by the *xxx*GetDevCaps call. -Otherwise, if you do not have registered manufacturer and product IDs, simply use the GuidGen utility to generate the manufacturer and product GUIDs. (GuidGen is included in the Microsoft Windows SDK.) When a driver's GUIDs are of this type, WDMAud loads default constants MM\_UNMAPPED and MM\_PID\_UNMAPPED into the **wMid** and **wPid** members, respectively, of the capabilities structure that is filled in by the *xxx*GetDevCaps call. +WDMAud uses the **Name** GUID in the KSCOMPONENTID structure to look up a "Name" key in the registry. These values are stored in *MediaCategories* in the registry. -WDMAud uses the **Name** GUID in the KSCOMPONENTID structure to look up a "Name" key in the registry. This key is located under the registry path name HKLM\\System\\CurrentControlSet\\Control\\MediaCategories. The "Name" key for a device has an associated string value that contains the device name. The *xxx*GetDevCaps function copies the first 31 characters of this name string into the **szPname** member of the capabilities structure. For device names longer than 31 characters, a client application can open the registry key and directly read the entire string. A driver can populate this registry entry in one of two ways: +The "Name" key for a device has an associated string value that contains the device name. The *xxx*GetDevCaps function copies the first 31 characters of this name string into the **szPname** member of the capabilities structure. A driver can populate this registry entry in one of two ways: - The driver can specify the entry in the device's INF file at install time. @@ -115,7 +114,7 @@ If the filter exposes no handler for the KSPROPERTY\_GENERAL\_COMPONENTID proper MM\_MSFT\_WDMAUDIO\_AUX - **vDriverVersion** = 0x050a (for Windows XP) or 0x0500 (pre-Windows XP) -On Windows releases earlier than Windows XP, the legacy members of the capabilities structure are always set to the defaults above. On Windows XP and later, the default values for the extended capabilities are as follows: +The default values for the extended capabilities are as follows: - **NameGuid** = GUID\_NULL diff --git a/windows-driver-docs-pr/audio/friendly-names-for-audio-endpoint-devices.md b/windows-driver-docs-pr/audio/friendly-names-for-audio-endpoint-devices.md index 72e5aaf209..9353a36bd8 100644 --- a/windows-driver-docs-pr/audio/friendly-names-for-audio-endpoint-devices.md +++ b/windows-driver-docs-pr/audio/friendly-names-for-audio-endpoint-devices.md @@ -1,7 +1,7 @@ --- title: Friendly Names for Audio Endpoint Devices description: Friendly Names for Audio Endpoint Devices -ms.date: 04/20/2017 +ms.date: 08/15/2022 --- # Friendly Names for Audio Endpoint Devices @@ -19,15 +19,15 @@ In addition the **PCPIN\_DESCRIPTOR** includes a GUID that can be used to identi The audio subsystem invokes the **KSPROPERTY\_PIN\_NAME** property to associate a friendly name with an audio endpoint. KS handles this request by first searching for a unicode string in the registry describing the **KsPinDescriptor.Name** GUID. If KS does not find an entry, it searches the registry for a unicode string describing the **KsPinDescriptor.Category** GUID. -Starting with **Windows 10 REDSTONE 5** when searching the registry, KS first looks for an entry in the device's software key. This is created by the INF through an AddReg section referenced by the [Models] section of the device driver's INF. The AddReg section constructs these entries using the HKR\\MediaCategories key. This allows the driver developer to create device-specific friendly names for both Name and Category GUIDs, whether the GUID is unique to the device or not. +Starting with Windows 10 October 2018 Update, version 1809, when searching the registry, KS first looks for an entry in the device's software key. This is created by the INF through an AddReg section referenced by the [Models] section of the device driver's INF. The AddReg section constructs these entries using the HKR\\MediaCategories key. This allows the driver developer to create device-specific friendly names for both Name and Category GUIDs, whether the GUID is unique to the device or not. -If an entry has not been installed in the device's software key or the driver is running on an operating system prior to **Windows 10 REDSTONE 5**, KS looks under HKLM\\SYSTEM\\CurrentControlSet\\Control\\MediaCategories registry key. This second key is treated as a global name space. Starting with **Windows 10 REDSTONE 5** this space is reserved for global definitions and should not be modified by new drivers. Modification of entries under this key will not be supported in a future OS release. +If an entry has not been installed in the device's software key or the driver is running on an operating system prior to Windows 10 version 1809, KS checks the MediaCategories registry key. This second key is treated as a global name space. Starting with Windows 10 version 1809 this space is reserved for global definitions and should not be modified by new drivers. Modification of entries under this key will not be supported in a future OS release. Audio devices that expose pins with standard categories GUIDs should include / needs the inbox KS.INF or KSCAPTUR.INF name registration in your device INF. These inbox INFs contain default friendly name definitions for pre-defined category GUIDs that your driver may wish to populate. These are the same GUIDs found in the **KsPinDescriptor.Category** member of the PCPIN\_DESCRIPTOR structure. For example, the category GUID KSNODETYPE\_MICROPHONE entry has the associated friendly name "microphone" and the category GUID KSNODETYPE\_SPEAKER entry has the associated friendly name "speakers," and so on. -The GUIDs and friendly names for both Category and Name GUIDs are stored under the HKR\\MediaCategories while global definitions HKLM\\SYSTEM\\CurrentControlSet\\Control\\MediaCategories paths. For each GUID-name pair in the registry, the GUID string is used as a sub-key under the MediaCategories key. Under the GUID key the friendly name a Unicode string value under the "Name" variable. +The GUIDs and friendly names for both Category and Name GUIDs are stored in the registry. For each GUID-name pair in the registry, the GUID string is used as a sub-key under the MediaCategories key. Under the GUID key the friendly name a Unicode string value under the "Name" variable. -If none of the friendly names and pin categories defined by the audio subsystem adequately describes your device, you can define your own pin category and name GUIDs and associate friendly names with them in your INF. To ensure that your pin-category GUID is unique, use a utility such as Uuidgen.exe to generate the GUID. Next, modify the INF file that installs your audio adapter to write the pin-category GUID and friendly name to the registry path HKR\\MediaCategories. The following code example shows a fragment of an INF file that adds two pin-category GUIDs and their associated friendly names to the registry: +If none of the friendly names and pin categories defined by the audio subsystem adequately describes your device, you can define your own pin category and name GUIDs and associate friendly names with them in your INF. To ensure that your pin-category GUID is unique, use a utility such as Uuidgen.exe to generate the GUID. Next, modify the INF file that installs your audio adapter to write the pin-category GUID and friendly name to the registry. The following code example shows a fragment of an INF file that adds two pin-category GUIDs and their associated friendly names to the registry: ```inf [Manufacturer] @@ -66,7 +66,7 @@ Both GUID strings were generated by Uuidgen.exe. Applications can access the properties of an audio endpoint device by using the device's **IPropertyStore** interface. The interface uses the property keys defined in the Functiondiscoverykeys\_devpkey.h and Mmdeviceapi.h header files to identify the properties. An application can use the **PKEY\_Device\_FriendlyName** property key to retrieve the friendly name of an endpoint device. For space-constrained user interfaces, a shorter version of the friendly name can be retrieved by using the **PKEY\_Device\_DeviceDesc** property key. For more information about these property keys, see [IMMDevice::OpenPropertyStore](/windows/win32/api/mmdeviceapi/nf-mmdeviceapi-immdevice-openpropertystore). -An **IPropertyStore** interface instance maintains a persistent property store for an audio endpoint device. The property store copies its initial value for the **PKEY\_Device\_DeviceDesc** property key from the friendly name string that is associated with the KS pin category GUID in the registry path HKLM\\SYSTEM\\CurrentControlSet\\Control\\MediaCategories. Applications can read the **PKEY\_Device\_DeviceDesc** property value (the name string) from the property store, but they cannot change the value. However, users can modify the name by using the Windows multimedia control panel, Mmsys.cpl. For example, in Windows Vista, you can use the following steps to modify the name of a rendering endpoint device: +An **IPropertyStore** interface instance maintains a persistent property store for an audio endpoint device. The property store copies its initial value for the **PKEY\_Device\_DeviceDesc** property key from the friendly name string that is associated with the KS pin category GUID in the registry. Applications can read the **PKEY\_Device\_DeviceDesc** property value (the name string) from the property store, but they cannot change the value. However, users can modify the name by using the Windows multimedia control panel, Mmsys.cpl. For example, in Windows Vista, you can use the following steps to modify the name of a rendering endpoint device: 1. To run Mmsys.cpl, open a Command Prompt window and enter the following command: diff --git a/windows-driver-docs-pr/audio/glitch-reporting-for-offloaded-audio.md b/windows-driver-docs-pr/audio/glitch-reporting-for-offloaded-audio.md index b1f03cfe7d..de5027dee5 100644 --- a/windows-driver-docs-pr/audio/glitch-reporting-for-offloaded-audio.md +++ b/windows-driver-docs-pr/audio/glitch-reporting-for-offloaded-audio.md @@ -13,7 +13,7 @@ When an audio driver detects glitching errors, it must raise an Event Tracing fo The following enum shows the events that have been defined for the audio driver to use for glitch error reporting. -```ManagedCPlusPlus +```cpp typedef enum { eMINIPORT_IHV_DEFINED = 0, @@ -30,6 +30,3 @@ typedef enum For more information about this enum, see [**EPcMiniportEngineEvent**](/windows-hardware/drivers/ddi/portcls/ne-portcls-epcminiportengineevent). And for more information about how to develop a driver that can handle hardware-offloaded audio streams, see [Driver Implementation Details](driver-implementation-details.md). - - - diff --git a/windows-driver-docs-pr/audio/hd-audio-bus-driver.md b/windows-driver-docs-pr/audio/hd-audio-bus-driver.md index fcda920773..7a95d6759d 100644 --- a/windows-driver-docs-pr/audio/hd-audio-bus-driver.md +++ b/windows-driver-docs-pr/audio/hd-audio-bus-driver.md @@ -1,50 +1,41 @@ --- -title: HD Audio Bus Driver -description: HD Audio Bus Driver +title: HD audio bus driver +description: HD audio bus driver keywords: -- HD Audio, Universal Audio Architecture -- High Definition Audio (HD Audio), Universal Audio Architecture +- HD audio, Universal Audio Architecture +- High Definition Audio (HD audio), Universal Audio Architecture - UAA WDK - Universal Audio Architecture WDK - bus drivers WDK audio -- HD Audio, bus driver -- High Definition Audio (HD Audio), bus driver -ms.date: 04/20/2017 +- HD audio, bus driver +- High Definition Audio (HD audio), bus driver +ms.date: 10/28/2022 --- -# HD Audio Bus Driver +# HD audio bus driver +The HD audio bus driver is the only software component that directly accesses the hardware registers of the HD audio bus interface controller. The bus driver exposes the HD audio DDI that its children--instances of the function drivers that control the audio and modem codecs--can use to program the HD audio controller hardware. In addition, the bus driver manages the HD audio link hardware resources, which include the DMA engines and bus bandwidth. Function drivers allocate and free these resources through the HD audio DDI. -The HD Audio bus driver is the only software component that directly accesses the hardware registers of the HD Audio bus interface controller. The bus driver exposes the HD Audio DDI that its children--instances of the function drivers that control the audio and modem codecs--can use to program the HD Audio controller hardware. In addition, the bus driver manages the HD Audio Link hardware resources, which include the DMA engines and bus bandwidth. Function drivers allocate and free these resources through the HD Audio DDI. +The HD audio bus driver: -The HD Audio bus driver: +- Queries the codecs on the bus and creates children to manage the codecs. -- Queries the codecs on the bus and creates children to manage the codecs. +- Handles interrupt service routines (ISRs) for unsolicited responses and propagates the unsolicited responses to its children. -- Handles interrupt service routines (ISRs) for unsolicited responses and propagates the unsolicited responses to its children. +- Passes commands from its children to the codecs and retrieves responses from the codecs. -- Passes commands from its children to the codecs and retrieves responses from the codecs. +- Sets up the DMA engines that transfer data to or from the cyclic buffers. -- Sets up the DMA engines that transfer data to or from the cyclic buffers. +- Manages bus bandwidth resources on the HD audio link. -- Manages bus bandwidth resources on the HD Audio Link. +- Provides access to the wall clock register and link position registers. -- Provides access to the wall clock register and link position registers. - -- Provides synchronized starting and stopping of groups of streams. - -The HD Audio bus driver does not provide: - -- An interface for programming a DSP or additional registers that are not defined in the Intel High Definition Audio Specification. - -- Prioritized bandwidth management. - -During device enumeration, the HD Audio bus driver detects the codecs that are attached to the HD Audio controller's HD Audio Link. For each codec, the bus driver loads one function driver (if available) for each function group that it finds within the codec. For information about function groups, see the Intel High Definition Audio Specification at the [Intel HD Audio](https://www.intel.com/content/www/us/en/standards/intel-standards-and-initiatives.html) website. - - - - +- Provides synchronized starting and stopping of groups of streams. +The HD audio bus driver doesn't provide: +- An interface for programming a DSP or other registers that aren't defined in the Intel High Definition Audio Specification. +- Prioritized bandwidth management. +During device enumeration, the HD audio bus driver detects the codecs that are attached to the HD audio controller's HD audio link. For each codec, the bus driver loads one function driver (if available) for each function group that it finds within the codec. For information about function groups, see the Intel High Definition Audio Specification at the [Intel HD audio](https://www.intel.com/content/www/us/en/standards/high-definition-audio-specification.html) website. diff --git a/windows-driver-docs-pr/audio/hd-audio-ddi-enumerations.md b/windows-driver-docs-pr/audio/hd-audio-ddi-enumerations.md index f33e97e508..27f50bb739 100644 --- a/windows-driver-docs-pr/audio/hd-audio-ddi-enumerations.md +++ b/windows-driver-docs-pr/audio/hd-audio-ddi-enumerations.md @@ -1,9 +1,11 @@ --- title: HD Audio DDI Enumerations description: This section describes the enumerations that are used by various HD audio properties and structures. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # HD Audio DDI Enumerations diff --git a/windows-driver-docs-pr/audio/helper-interfaces-for-offloaded-audio-processing.md b/windows-driver-docs-pr/audio/helper-interfaces-for-offloaded-audio-processing.md index d65ea384d9..e5099a6007 100644 --- a/windows-driver-docs-pr/audio/helper-interfaces-for-offloaded-audio-processing.md +++ b/windows-driver-docs-pr/audio/helper-interfaces-for-offloaded-audio-processing.md @@ -1,26 +1,24 @@ --- title: Helper Interfaces for Offloaded Audio Processing description: This topic presents the PortCls helper interfaces, to simplify the drivers that support offloaded-audio processing. -ms.date: 04/20/2017 +ms.date: 05/31/2023 --- # Helper Interfaces for Offloaded Audio Processing - This topic presents the helper interfaces that Microsoft has added to its audio port-class driver (PortCls), to simplify the implementation of drivers that support offloaded-audio processing. When you develop your WaveRT miniport driver that will work with an audio adapter that is capable of processing hardware-offloaded audio streams, your miniport driver works with PortCls to stream and/or process audio data. PortCls has been updated to handle all the offload-related kernel streaming (KS) properties, and that is what makes it simple to develop a WaveRT miniport driver to expose support for processing hardware-offloaded audio streams. As a result of the updates, PortCls only calls the underlying miniport driver for hardware and/or driver-specific operations via two newly defined interfaces: -- [**IMiniportAudioEngineNode**](/windows-hardware/drivers/ddi/portcls/nn-portcls-iminiportaudioenginenode) +- [**IMiniportAudioEngineNode**](/windows-hardware/drivers/ddi/portcls/nn-portcls-iminiportaudioenginenode) -- [**IMiniportStreamAudioEngineNode**](/windows-hardware/drivers/ddi/portcls/nn-portcls-iminiportstreamaudioenginenode) +- [**IMiniportStreamAudioEngineNode**](/windows-hardware/drivers/ddi/portcls/nn-portcls-iminiportstreamaudioenginenode) You must develop two classes to work with these interfaces, one for each interface. -## Working with IMiniportAudioEngineNode - +## Working with IMiniportAudioEngineNode The class that you develop to work with **IMiniportAudioEngineNode**, must also inherit from [IMiniportWaveRT](/windows-hardware/drivers/ddi/portcls/nn-portcls-iminiportwavert). The methods defined in **IMiniportAudioEngineNode** allow your driver to use KS properties that access the audio engine via a KS filter handle. The class/interface hierarchy is as follows: @@ -30,7 +28,7 @@ So if, for example, you develop a class called CYourMiniportWaveRT, then as you A skeletal template for such a class would contain the following code: -```ManagedCPlusPlus +```cpp class CMiniportWaveRT : public IMiniportWaveRT, public IMiniportAudioEngineNode, @@ -47,8 +45,7 @@ class CMiniportWaveRT : The *Portcls.h* header file defines these interfaces. -## Working with IMiniportStreamAudioEngineNode - +## Working with IMiniportStreamAudioEngineNode The class that you develop to work with the second interface, **IMiniportStreamAudioEngineNode**, must also inherit from [IMiniportWaveRTStreamNotification](/windows-hardware/drivers/ddi/portcls/nn-portcls-iminiportwavertstreamnotification). The methods defined in **IMiniportStreamAudioEngineNode** allow your driver to use KS properties that access the audio engine via a pin instance handle. The class/interface hierarchy is as follows: @@ -58,7 +55,7 @@ So if, for example, you develop a class called CYourMiniportWaveRTStream, then a A skeletal template for such a class would contain the following code: -```ManagedCPlusPlus +```cpp class CMiniportWaveRTStream : public IMiniportWaveRTStreamNotification, public IMiniportStreamAudioEngineNode, @@ -74,6 +71,3 @@ class CMiniportWaveRTStream : ``` The *Portcls.h* header file defines these interfaces. And for more information about how to develop a driver that can handle hardware-offloaded audio streams, see [Driver Implementation Details](driver-implementation-details.md). - - - diff --git a/windows-driver-docs-pr/audio/hfp-device-connection.md b/windows-driver-docs-pr/audio/hfp-device-connection.md index 604755068c..d489a7f8eb 100644 --- a/windows-driver-docs-pr/audio/hfp-device-connection.md +++ b/windows-driver-docs-pr/audio/hfp-device-connection.md @@ -1,48 +1,46 @@ --- -title: HFP Device Connection -description: The HFP Device connection topic discusses how the audio system determines and handles connection status information for a Bluetooth hands-free profile (HFP) device. -ms.date: 04/20/2017 +title: HFP device connection +description: This article discusses how the audio system determines and handles connection status information for a Bluetooth hands-free profile (HFP) device. +ms.date: 07/27/2023 --- -# HFP Device Connection +# HFP device connection +This article discusses how the audio system determines and handles connection status information for a Bluetooth hands-free profile (HFP) device. -The HFP Device connection topic discusses how the audio system determines and handles connection status information for a Bluetooth hands-free profile (HFP) device. +The audio driver must support [**KSPROPERTY_JACK_DESCRIPTION**](./ksproperty-jack-description.md) and maintain an *IsConnected* field in the filter factory context. The driver uses this value when handling the **KSPROPERTY_JACK_DESCRIPTION** property. -As required for all audio drivers, the audio driver must support [**KSPROPERTY\_JACK\_DESCRIPTION**](./ksproperty-jack-description.md). The audio driver maintains an *IsConnected* field in the filter factory context. The audio driver uses this value when handling the **KSPROPERTY\_JACK\_DESCRIPTION** property. +When [**IOCTL_BTHHFP_DEVICE_GET_CONNECTION_STATUS_UPDATE**](/windows-hardware/drivers/ddi/bthhfpddi/ni-bthhfpddi-ioctl_bthhfp_device_get_connection_status_update) completes successfully, the audio driver updates *IsConnected* with the new connection status. If the status has changed, the audio driver raises the [**KSEVENT_PINCAPS_JACKINFOCHANGE**](./ksevent-pincaps-jackinfochange.md) event, causing the audio system to reevaluate the connection state. The audio driver then calls another instance of **IOCTL_BTHHFP_DEVICE_GET_CONNECTION_STATUS_UPDATE** to receive the next status change. If an earlier status change request is still pending, this second call fails, and the audio driver doesn't update its connection status and doesn't make another request for status change information. -When [**IOCTL\_BTHHFP\_DEVICE\_GET\_CONNECTION\_STATUS\_UPDATE**](/windows-hardware/drivers/ddi/bthhfpddi/ni-bthhfpddi-ioctl_bthhfp_device_get_connection_status_update) completes successfully, then the audio driver updates *IsConnected* with the new connection status. If the status has changed, the audio driver raises the [**KSEVENT\_PINCAPS\_JACKINFOCHANGE**](./ksevent-pincaps-jackinfochange.md) event, which causes the audio system to reevaluate the connection state. The audio driver then calls another instance of **IOCTL\_BTHHFP\_DEVICE\_GET\_CONNECTION\_STATUS\_UPDATE** to receive the next status change. If there is an earlier status change request that is still pending, then this second call will fail, the audio driver doesn't update its connection status, and doesn't make another request for status change information. +As discussed in [Kernel streaming considerations](kernel-streaming-considerations.md), the audio driver must support [**KSPROPERTY_ONESHOT_RECONNECT**](./ksproperty-oneshot-reconnect.md) and [**KSPROPERTY_ONESHOT_DISCONNECT**](./ksproperty-oneshot-disconnect.md). The handlers for these properties must send REQUESTCONNECT and REQUESTDISCONNECT IOCTLs, respectively, to the HFP driver. These IOCTLs complete quickly, and the audio driver needs to be ready to respond to the returned results. -As discussed in [Kernel Streaming Considerations](kernel-streaming-considerations.md), the audio driver must support [**KSPROPERTY\_ONESHOT\_RECONNECT**](./ksproperty-oneshot-reconnect.md) and [**KSPROPERTY\_ONESHOT\_DISCONNECT**](./ksproperty-oneshot-disconnect.md), and the handlers for these properties must send REQUESTCONNECT and REQUESTDISCONNECT IOCTLs respectively, to the HFP driver. These IOCTLs complete quickly, and the audio driver needs to be ready to respond to the returned results. +This article also covers other Bluetooth audio device connection-related factors that the audio driver developer must be aware of. -Here are some other Bluetooth audio device connection-related factors that the audio driver developer must be aware of. +## Stream channel -## Stream channel +The stream channel represents the audio driver's allocation of over-the-air bandwidth. For the most part, this is the SCO channel. However, some of the details of managing the SCO channel status are handled entirely within the HFP driver. This includes for example remote disconnects which may be due to call scenarios where the HF initiates an audio transfer to the AG (with the PC playing the role of the AG in this case). +## Audio filter pin states -The Stream Channel represents the audio driver’s allocation of over-the-air bandwidth. For the most part, this is the SCO channel. However, some of the details of managing the SCO channel status are handled entirely within the HFP driver. This includes for example remote disconnects which may be due to call scenarios where the HF initiates an audio transfer to the AG (where the PC plays the role of the AG in this case). +The audio driver implements KS pin state handlers for two KS pins. The SCO stream channel is required for either of these pins to transfer data over the air. When either of these pins transitions to KSSTATE_ACQUIRE, the audio driver opens the channel by sending [**IOCTL_BTHHFP_STREAM_OPEN**](/windows-hardware/drivers/ddi/bthhfpddi/ni-bthhfpddi-ioctl_bthhfp_stream_open) to the HFP driver. This asynchronous call may take several seconds to complete. The audio driver doesn't need to implement its own timeout mechanism and should wait for the IOCTL to complete before completing the transition to KSSTATE_ACQUIRE. -## Audio filter pin states +When both KS pins transition to KSSTATE_STOP, the audio driver sends [**IOCTL_BTHHFP_STREAM_CLOSE**](/windows-hardware/drivers/ddi/bthhfpddi/ni-bthhfpddi-ioctl_bthhfp_stream_close) to the HFP driver, which completes quickly. +To determine when to send **IOCTL_BTHHFP_STREAM_OPEN** and **IOCTL_BTHHFP_STREAM_CLOSE**, the audio driver can use a simple reference counting mechanism to track the number of pins that require the SCO stream channel. The audio driver would open and close the SCO stream channel when the reference count changes from 0 to 1. -The audio driver implements a KS pin state handlers (similar to AVStrMiniPinSetDeviceState) for two KS pins. The SCO stream channel is required for either of these pins to transfer data over the air. When either of these pins transitions to KSSTATE\_ACQUIRE, the audio driver opens the channel by sending [**IOCTL\_BTHHFP\_STREAM\_OPEN**](/windows-hardware/drivers/ddi/bthhfpddi/ni-bthhfpddi-ioctl_bthhfp_stream_open) to the HFP driver. This is an asynchronous call and may take several seconds to complete. The audio driver does not need to implement its own timeout mechanism and should wait for the IOCTL to complete before completing the transition to KSSTATE\_ACQUIRE. +On **IOCTL_BTHHFP_STREAM_OPEN**, the HFP driver requests an SCO channel, if one is not already open, and completes the request with the results from the SCO request. On **IOCTL_BTHHFP_STREAM_CLOSE**, the HFP driver requests a SCO channel disconnect, if one is open. -When both KS pins transition to KSSTATE\_STOP, the audio driver sends [**IOCTL\_BTHHFP\_STREAM\_CLOSE**](/windows-hardware/drivers/ddi/bthhfpddi/ni-bthhfpddi-ioctl_bthhfp_stream_close) to the HFP driver. This completes quickly. +## Remote SCO connect and disconnect -To determine when to send **IOCTL\_BTHHFP\_STREAM\_OPEN** and **IOCTL\_BTHHFP\_STREAM\_CLOSE**, the audio driver can use a simple reference counting mechanism to track the number of pins that require the SCO stream channel. The audio driver would open and close the SCO stream channel when the reference count changes from 0 to 1. - -On **IOCTL\_BTHHFP\_STREAM\_OPEN**, the HFP driver requests an SCO channel, if one is not already open, and completes the request with the results from the SCO request. On **IOCTL\_BTHHFP\_STREAM\_CLOSE** the HFP driver requests a SCO channel disconnect, if one is open. - -## Remote SCO connect and disconnect - - -On a remote SCO disconnect, if the Stream Channel is closed, the HFP driver does nothing. If the Stream Channel is opened the HFP driver will start a reconnect timer. When the timer expires, if SCO is still disconnected and Stream Channel is still open then the driver will request a SCO channel. Note that no audio data transfers over the air while SCO is disconnected so there will be a gap in audio during this period. If the SCO request fails then the HFP driver will signal a Stream Channel status change to the audio driver by completing any invoking [**IOCTL\_BTHHFP\_STREAM\_GET\_STATUS\_UPDATE**](/windows-hardware/drivers/ddi/bthhfpddi/ni-bthhfpddi-ioctl_bthhfp_stream_get_status_update). This should be rare, as remote SCO disconnect is normally associated with the HF device requesting transfer of call audio to the audio gateway. The audio driver should consider this a mid-stream error condition. +On a remote SCO disconnect, if the stream channel is closed, the HFP driver does nothing. If the stream channel is opened, the HFP driver starts a reconnect timer. When the timer expires, if SCO is still disconnected and the stream channel is still open, the driver requests a SCO channel. Note that no audio data transfers over the air while SCO is disconnected, so there will be a gap in audio during this period. If the SCO request fails, the HFP driver signals a stream channel status change to the audio driver by completing any invoking [**IOCTL_BTHHFP_STREAM_GET_STATUS_UPDATE**](/windows-hardware/drivers/ddi/bthhfpddi/ni-bthhfpddi-ioctl_bthhfp_stream_get_status_update). This should be rare, as remote SCO disconnect is normally associated with the HF device requesting transfer of call audio to the audio gateway. The audio driver should consider this a mid-stream error condition. This procedure allows time for a VoIP application to receive an audio transfer callback from the CallButtons API and cleanly release its audio resources on the HFP endpoint, instead of causing streaming errors. -On a remote SCO connect, if the Stream Channel is open the driver simply accepts the connection. If the Stream Channel is closed, then the HFP driver accepts the connection and also starts a disconnect timer. When the disconnect timer expires, if SCO is still connected and the Stream channel is still closed, then the driver will break the SCO connection. +On a remote SCO connect, if the stream channel is open, the driver simply accepts the connection. If the stream channel is closed, the HFP driver accepts the connection and starts a disconnect timer. When the disconnect timer expires, if SCO is still connected and the stream channel is still closed, the driver breaks the SCO connection. This procedure allows time for a VoIP application to receive an audio transfer callback from the CallButtons API and establish audio resources on the HFP endpoint, without prematurely rejecting or closing the SCO connection. -## Related topics -[Theory of Operation](theory-of-operation.md) +## Related topics + +- [Bluetooth HFP bypass audio streaming](bluetooth-hfp-bypass-audio-streaming.md) +- [Bluetooth Low Energy (LE) Audio](../bluetooth/bluetooth-low-energy-audio.md) diff --git a/windows-driver-docs-pr/audio/iaudiosystemeffects.md b/windows-driver-docs-pr/audio/iaudiosystemeffects.md index 8a69803f98..82d5d77b11 100644 --- a/windows-driver-docs-pr/audio/iaudiosystemeffects.md +++ b/windows-driver-docs-pr/audio/iaudiosystemeffects.md @@ -1,15 +1,12 @@ --- title: IAudioSystemEffects description: IAudioSystemEffects -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- # IAudioSystemEffects - The IAudioSystemEffects interface uses the basic methods that are inherited from **IUnknown**, and must implement an **Initialize** method. The parameters that are passed to this **Initialize** method must be passed directly to the **IAudioProcessingObject::Initialize** method. Refer to the [**IAudioProcessingObject::Initialize**](/windows/win32/api/audioenginebaseapo/nf-audioenginebaseapo-iaudioprocessingobject-initialize) method for information about the structure and the parameters that are required to implement the **IAudioSystemEffects::Initialize** method. - - - diff --git a/windows-driver-docs-pr/audio/iaudiosystemeffects2.md b/windows-driver-docs-pr/audio/iaudiosystemeffects2.md index 0a503a8711..4c94f2b90d 100644 --- a/windows-driver-docs-pr/audio/iaudiosystemeffects2.md +++ b/windows-driver-docs-pr/audio/iaudiosystemeffects2.md @@ -4,11 +4,12 @@ description: The IAudioSystemEffects2 interface was introduced with Windows 8.1 keywords: ["IAudioSystemEffects2 interface Audio Devices", "IAudioSystemEffects2 interface Audio Devices , described"] topic_type: - apiref +ms.topic: reference api_name: - IAudioSystemEffects2 api_type: - COM -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- # IAudioSystemEffects2 interface diff --git a/windows-driver-docs-pr/audio/ikeyworddetectoroemadapter.md b/windows-driver-docs-pr/audio/ikeyworddetectoroemadapter.md index 737a0a72e6..6832efa9d3 100644 --- a/windows-driver-docs-pr/audio/ikeyworddetectoroemadapter.md +++ b/windows-driver-docs-pr/audio/ikeyworddetectoroemadapter.md @@ -4,15 +4,16 @@ description: IKeywordDetectorOemAdapter is a Component Object Model (COM) interf keywords: ["IKeywordDetectorOemAdapter interface Audio Devices", "IKeywordDetectorOemAdapter interface Audio Devices , described"] topic_type: - apiref +ms.topic: reference api_name: - IKeywordDetectorOemAdapter api_type: - COM -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- -# IKeywordDetectorOemAdapter interface +# IKeywordDetectorOemAdapter interface **IKeywordDetectorOemAdapter** is a Component Object Model (COM) interface for interacting with the Voice Activation Driver Interface. The **IKeywordDetectorOemAdapter** interface is supported in Windows 10 and later versions of Windows. diff --git a/windows-driver-docs-pr/audio/images/audio-acx-multi-stack-acx-manager-related-objects.png b/windows-driver-docs-pr/audio/images/audio-acx-multi-stack-acx-manager-related-objects.png new file mode 100644 index 0000000000..44aa630e87 Binary files /dev/null and b/windows-driver-docs-pr/audio/images/audio-acx-multi-stack-acx-manager-related-objects.png differ diff --git a/windows-driver-docs-pr/audio/images/audio-acx-multi-stack-kernel-streaming.png b/windows-driver-docs-pr/audio/images/audio-acx-multi-stack-kernel-streaming.png new file mode 100644 index 0000000000..520b4d1826 Binary files /dev/null and b/windows-driver-docs-pr/audio/images/audio-acx-multi-stack-kernel-streaming.png differ diff --git a/windows-driver-docs-pr/audio/images/audio-acx-multi-stack-multi-circuit-driver-sequence.png b/windows-driver-docs-pr/audio/images/audio-acx-multi-stack-multi-circuit-driver-sequence.png new file mode 100644 index 0000000000..3f849714be Binary files /dev/null and b/windows-driver-docs-pr/audio/images/audio-acx-multi-stack-multi-circuit-driver-sequence.png differ diff --git a/windows-driver-docs-pr/audio/images/audio-acx-multi-stream-flow-sequence.png b/windows-driver-docs-pr/audio/images/audio-acx-multi-stream-flow-sequence.png new file mode 100644 index 0000000000..c5f1867864 Binary files /dev/null and b/windows-driver-docs-pr/audio/images/audio-acx-multi-stream-flow-sequence.png differ diff --git a/windows-driver-docs-pr/audio/images/audio-apo-enhancements-properties.png b/windows-driver-docs-pr/audio/images/audio-apo-enhancements-properties.png deleted file mode 100644 index 978545dda8..0000000000 Binary files a/windows-driver-docs-pr/audio/images/audio-apo-enhancements-properties.png and /dev/null differ diff --git a/windows-driver-docs-pr/audio/images/audio-apo-sound-properties.png b/windows-driver-docs-pr/audio/images/audio-apo-sound-properties.png deleted file mode 100644 index 4d907067f6..0000000000 Binary files a/windows-driver-docs-pr/audio/images/audio-apo-sound-properties.png and /dev/null differ diff --git a/windows-driver-docs-pr/audio/images/audio-apo-speaker-properties.png b/windows-driver-docs-pr/audio/images/audio-apo-speaker-properties.png deleted file mode 100644 index a230bcb2fd..0000000000 Binary files a/windows-driver-docs-pr/audio/images/audio-apo-speaker-properties.png and /dev/null differ diff --git a/windows-driver-docs-pr/audio/images/audio-voice-activation-and-speaker-id.png b/windows-driver-docs-pr/audio/images/audio-voice-activation-and-speaker-id.png deleted file mode 100644 index 7e490b0e9d..0000000000 Binary files a/windows-driver-docs-pr/audio/images/audio-voice-activation-and-speaker-id.png and /dev/null differ diff --git a/windows-driver-docs-pr/audio/images/btth-bypass-arch.png b/windows-driver-docs-pr/audio/images/btth-bypass-arch.png index 5904544343..db4ac5b802 100644 Binary files a/windows-driver-docs-pr/audio/images/btth-bypass-arch.png and b/windows-driver-docs-pr/audio/images/btth-bypass-arch.png differ diff --git a/windows-driver-docs-pr/audio/images/cortana-settings-respond-to-anyone.png b/windows-driver-docs-pr/audio/images/cortana-settings-respond-to-anyone.png deleted file mode 100644 index 604ddc230f..0000000000 Binary files a/windows-driver-docs-pr/audio/images/cortana-settings-respond-to-anyone.png and /dev/null differ diff --git a/windows-driver-docs-pr/audio/images/setfmt1.png b/windows-driver-docs-pr/audio/images/setfmt1.png deleted file mode 100644 index f0c0105e8d..0000000000 Binary files a/windows-driver-docs-pr/audio/images/setfmt1.png and /dev/null differ diff --git a/windows-driver-docs-pr/audio/images/setfmt2.png b/windows-driver-docs-pr/audio/images/setfmt2.png deleted file mode 100644 index 0c6eff7f19..0000000000 Binary files a/windows-driver-docs-pr/audio/images/setfmt2.png and /dev/null differ diff --git a/windows-driver-docs-pr/audio/images/setfmt3.png b/windows-driver-docs-pr/audio/images/setfmt3.png deleted file mode 100644 index 61fe1efc20..0000000000 Binary files a/windows-driver-docs-pr/audio/images/setfmt3.png and /dev/null differ diff --git a/windows-driver-docs-pr/audio/images/sysfxapo-ms-components.png b/windows-driver-docs-pr/audio/images/sysfxapo-ms-components.png deleted file mode 100644 index 0c627658a3..0000000000 Binary files a/windows-driver-docs-pr/audio/images/sysfxapo-ms-components.png and /dev/null differ diff --git a/windows-driver-docs-pr/audio/immediate-idle-timeout-opt-in.md b/windows-driver-docs-pr/audio/immediate-idle-timeout-opt-in.md index c6c3b8686f..ebb9167ec7 100644 --- a/windows-driver-docs-pr/audio/immediate-idle-timeout-opt-in.md +++ b/windows-driver-docs-pr/audio/immediate-idle-timeout-opt-in.md @@ -1,39 +1,39 @@ --- title: Immediate Idle Timeout Opt-in description: This topic discusses the ImmediateIdle registry value that a Windows 8 driver can use to opt-in to an immediate power down state, when power is no longer needed. -ms.date: 04/20/2017 +ms.date: 08/17/2022 --- # Immediate Idle Timeout Opt-in -This topic discusses the *ImmediateIdle* registry value that a Windows 8 driver can use to opt-in to an immediate power down state, when power is no longer needed. +This topic discusses the *ImmediateIdle* registry value that a Windows driver can use to opt-in to an immediate power down state, when power is no longer needed. -In addition to the default power settings discussed in [PortCls Registry Power Settings](portcls-registry-power-settings.md), Windows 8 introduces a new registry value that is also located in the PowerSettings registry key for the associated driver. For example, if you have a driver whose key is <UVXYZ>, then the power settings information for the driver would be found in the following path in the Windows registry: +In addition to the default power settings discussed in [PortCls Registry Power Settings](portcls-registry-power-settings.md), Windows 8 introduced an *ImmediateIdle* registry value that is also located in the PowerSettings registry key for the associated driver. -HKLM\\System\\CurrentControlSet\\Control\\Class\\{4D36E96C-E325-11CE-BFC1-08002BE10318}\\<UVXYZ>\\PowerSettings. +This inf file shows how to set *ImmediateIdle*. -And in addition to the default power setting values shown in [PortCls Registry Power Settings](portcls-registry-power-settings.md), you would also include the following line for *ImmediateIdle*: - -``` syntax -"ImmediateIdle"=hex:00,00,00,00 +```inf +[MyAudioDevice.AddReg] +HKR,PowerSettings,ImmediateIdle,%REG_BINARY%, 0x00, 0x00, 0x00, 0x00 ``` *ImmediateIdle* has a data type of REG\_DWORD and its default value is "0" which equates to FALSE. In the preceding syntax fragment, the hexadecimal value of "0" means that the device will not immediately power down when power is no longer needed. For your driver to opt-in to an immediate power down state, when power is no longer needed, you must use the following syntax: -``` syntax -"ImmediateIdle"=hex:01,00,00,00 +```inf +[MyAudioDevice.AddReg] +HKR,PowerSettings,ImmediateIdle,%REG_BINARY%, 0x01, 0x00, 0x00, 0x00 ``` -In the preceding syntax fragment, the hex value of "1" equates to TRUE, and it means that the device will immediately power down when power is no longer needed. +In the preceding example, the hex value of "1" equates to TRUE, and it means that the device will immediately power down when power is no longer needed. When the runtime power management framework invokes a callback for the **DevicePowerRequired** method, indicating that the device no longer requires power, PortCls then requests a Device Power IRP for the D-State indicated by the *IdlePowerState* registry value. If no state is supplied, then the default value of D3 is used. If a driver opts-in to immediate idle power management, it must ensure that the Power Engine Plug-in (PEP) for the system contains the logic needed to prevent unnecessarily and continuously powering the adapter up and down for IRPs received in immediate succession. Some residency rules should be applied in order to keep the device powered up for batches of I/O requests. -In addition, the new interface introduced in Windows 7 that allows drivers to programmatically enable or disable idle power management, continues to be honored when the driver has not opted-in to immediate idle power management. This is done via the [**IPortClsPower::SetIdlePowerManagement**](/windows-hardware/drivers/ddi/portcls/nf-portcls-iportclspower-setidlepowermanagement) method and would override the settings in the registry, except for the case in which *ImmediateIdle* is set to 1 (TRUE). +In addition, the interface introduced in Windows 7 that allows drivers to programmatically enable or disable idle power management, continues to be honored when the driver has not opted-in to immediate idle power management. This is done via the [**IPortClsPower::SetIdlePowerManagement**](/windows-hardware/drivers/ddi/portcls/nf-portcls-iportclspower-setidlepowermanagement) method and would override the settings in the registry, except for the case in which *ImmediateIdle* is set to 1 (TRUE). diff --git a/windows-driver-docs-pr/audio/implementing-audio-processing-objects.md b/windows-driver-docs-pr/audio/implementing-audio-processing-objects.md index 0ba5a9ffa1..1159c6e954 100644 --- a/windows-driver-docs-pr/audio/implementing-audio-processing-objects.md +++ b/windows-driver-docs-pr/audio/implementing-audio-processing-objects.md @@ -1,7 +1,7 @@ --- title: Implementing Audio Processing Objects description: This topic describes how to implement an audio processing object (APO). For general information about APOs, see Audio Processing Object Architecture. -ms.date: 06/11/2021 +ms.date: 05/05/2023 --- # Implementing Audio Processing Objects @@ -63,7 +63,7 @@ The SYSVAD audio sample is available on the [Windows Driver Samples GitHub](http You can browse the Sysvad audio sample here: - + ### Download and extract the Sysvad audio sample from GitHub @@ -222,7 +222,7 @@ Disable Use of an Embedded Manifest by setting project properties for your APO p ## Packaging your APO with a Driver -When you develop your own audio driver and wrap or replace the system-supplied APOs, you must provide a driver package for installing the driver and APOs. For Windows 10, please see [Universal Windows Drivers for Audio](audio-universal-drivers.md). Your audio related driver packages should follow the policies and packaging model detailed there. +When you develop your own audio driver and wrap or replace the system-supplied APOs, you must provide a driver package for installing the driver and APOs. For Windows 10, please see [Universal Windows Drivers for Audio](audio-universal-drivers.md). Your audio related driver packages should follow the policies and packaging model detailed there. The custom APO is packaged as a DLL, and any configuration UI is packaged as a separate UWP or Desktop Bridge app. The APO device INF copies the DLLs to the system folders that are indicated in the associated INF CopyFile directive. The DLL that contains the APOs must register itself by including an AddReg section in the INF file. @@ -263,7 +263,7 @@ There is one additional valid combination that is not shown in these samples. This sample shows a multi-mode streaming effect being registered using AddReg entries in the SYSVAD Tablet INF file. -This sample code is from the SYSVAD audio sample and is available on GitHub: . +This sample code is from the SYSVAD audio sample and is available on GitHub: . This sample illustrates this combination of system effects: @@ -298,7 +298,7 @@ Note that in the sample INF file, the EFX\_Streaming property is commented out b Starting with Windows 10, release 1809, APO registration with the audio engine uses the componentized audio driver model. Using audio componentization creates a smoother and more reliable install experience and better supports component servicing. For more information, see [Creating a componentized audio driver installation](./audio-universal-drivers.md#creating-a-componentized-audio-driver-installation). -The following example code is extracted from the public ComponentizedAudioSampleExtension.inf and ComponentizedApoSample.inf. Refer to the SYSVAD audio sample which is available on GitHub here: . +The following example code is extracted from the public ComponentizedAudioSampleExtension.inf and ComponentizedApoSample.inf. Refer to the SYSVAD audio sample which is available on GitHub here: . The registration of the APO with the audio engine is done using a newly created APO device. For the audio engine to make use of the new APO device it must be a PNP child of the audio device, sibling of the audio endpoints. The new componentized APO design does not allow for an APO to be registered globally and used by multiple different drivers. Each driver must register its own APO's. @@ -316,24 +316,25 @@ Description = "Audio Proxy APO Sample" This APO component triggers the second part, the installation of the APO INF, in the SYSVAD sample this is done in ComponentizedApoSample.inf. This INF file is dedicated to the APO component. It specifies the component class as AudioProcessingObject and adds all of the APO properties for CLSID registration and registering with the audio engine. >[!NOTE] -> The INF file samples shown support driver package isolation by using in most cases the HKR registry key. Earlier samples used the HKCR to store persistent values. The exception is that registration of Component Object Model (COM) objects, a key may be written under HKCR. - For more information, see [Using a Universal INF File](../install/using-a-universal-inf-file.md). +> The INF file samples shown support driver package isolation by using the HKR registry key. Before Windows 11, version 22000, the samples used the HKCR to store persistent values for CLSID registrations, instead of HKR. APO registration has been supported using HKR starting with Windows 10, release 1809. For more information, see [Using a Universal INF File](../install/using-a-universal-inf-file.md). + ```inf [Version] -Signature = "$WINDOWS NT$" +... Class = AudioProcessingObject ClassGuid = {5989fce8-9cd0-467d-8a6a-5419e31529d4} +... [ApoComponents.NT$ARCH$] %Apo.ComponentDesc% = ApoComponent_Install,APO\VEN_SMPL&CID_APO [Apo_AddReg] ; CLSID registration -HKCR,CLSID\%SWAP_FX_STREAM_CLSID%,,,%SFX_FriendlyName% -HKCR,CLSID\%SWAP_FX_STREAM_CLSID%\InProcServer32,,0x00020000,%%SystemRoot%%\System32\swapapo.dll -HKCR,CLSID\%SWAP_FX_STREAM_CLSID%\InProcServer32,ThreadingModel,,"Both" -… +HKR,Classes\CLSID\%SWAP_FX_STREAM_CLSID%,,,%SFX_FriendlyName% +HKR,Classes\CLSID\%SWAP_FX_STREAM_CLSID%\InProcServer32,,0x00020000,%%SystemRoot%%\System32\swapapo.dll +HKR,Classes\CLSID\%SWAP_FX_STREAM_CLSID%\InProcServer32,ThreadingModel,,"Both" +... ;Audio engine registration HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"FriendlyName",,%SFX_FriendlyName% ... @@ -341,6 +342,14 @@ HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"FriendlyName",,%S When this INF installs the componentized APO, on a desktop system "Audio Processing Objects" will be shown in Windows Device Manager. +### Updates to CLSIDs when a new APO version is released + +When a new APO version is released, it is a good practice and generally recommended to update the COM class CLSID. Use tools such as GUIDGEN to create new GUIDs. + +#### Requirement to Update CLSIDs when moving from HKCR to HKR + +It is a requirement when making the switch from global COM registrations (HKCR) to device relative HKR COM registrations to change the COM class GUID. This approach reduces the possibility that the new COM objects will not be registered properly and will fail to load. + ### Bluetooth Audio Sample APO INF Sample This sample illustrates this combination of system effects: @@ -438,7 +447,9 @@ HKR,"FX\\0",%PKEY_FX_EndpointEffectClsid%,,%FX_DISCOVER_EFFECTS_APO_CLSID% ### Sample APO Effect Registration -This sample shows the \[Apo_AddReg\] section from the Sysvad ComponentizedApoSample.inx. This section registers the swap stream GUID with COM and registers the Swap Stream APO effect. The \[Apo_CopyFiles\] section copies the swapapo.dll into C:\\Windows\\system32. +This sample shows the \[Apo_AddReg\] section from the Sysvad ComponentizedApoSample.inx. This section registers the swap stream GUID with COM and registers the Swap Stream APO effect. The \[Apo_CopyFiles\] section has a DestinationDirs of 13, which copies swapapo.dll into the Driverstore. For more information, see "Run From Driverstore" in [Driver Package Isolation](../develop/driver-isolation.md). + +For general information about INF files, see [Overview of INF Files](../install/overview-of-inf-files.md). ```inf ; ComponentizedApoSample.inx @@ -578,6 +589,6 @@ Also, if the failure count value for an SFX, MFX or EFX APO reaches a system-spe [Windows Audio Processing Objects](windows-audio-processing-objects.md) -[Using a Universal INF File](../install/using-a-universal-inf-file.md) - [Creating a componentized audio driver installation](./audio-universal-drivers.md#creating-a-componentized-audio-driver-installation) + +[Driver package isolation](../develop/driver-isolation.md) diff --git a/windows-driver-docs-pr/audio/kernel-streaming-considerations.md b/windows-driver-docs-pr/audio/kernel-streaming-considerations.md index f2be42881d..3e22cdb422 100644 --- a/windows-driver-docs-pr/audio/kernel-streaming-considerations.md +++ b/windows-driver-docs-pr/audio/kernel-streaming-considerations.md @@ -1,72 +1,71 @@ --- -title: Kernel Streaming Considerations -description: The Kernel Streaming considerations topic clarifies the requirements and other special considerations related to Bluetooth bypass audio streaming. +title: Kernel streaming considerations +description: This article clarifies the requirements and special considerations related to Bluetooth bypass audio streaming. ms.date: 04/20/2017 --- -# Kernel Streaming Considerations +# Kernel streaming considerations +This article clarifies the requirements and special considerations for kernel streaming related to Bluetooth bypass audio streaming. -The Kernel Streaming considerations topic clarifies the requirements and other special considerations beyond those for all audio drivers. These are kernel streaming considerations that are more related to Bluetooth bypass audio streaming. - -The audio driver should fully support the WaveRT port driver, including “pull mode.” For more information, see [Introducing the WaveRT Port Driver](introducing-the-wavert-port-driver.md). And although there is no requirement to implement a hardware audio engine for the synchronous connection oriented (SCO) bypass output, there is no harm in doing so. +The audio driver should fully support the WaveRT port driver, including "pull mode". For more information, see [Introducing the WaveRT port driver](introducing-the-wavert-port-driver.md). Although there is no requirement to implement a hardware audio engine for the synchronous connection oriented (SCO) bypass output, there is no harm in doing so. The Windows logo requirements for format support include an exception for Bluetooth. -The audio driver should support the formats that are possible through the sideband hardware. This is typically 8KHz mono audio streaming. +The audio driver should support the formats that are possible through the sideband hardware, typically 8kHz mono audio streaming. -## Topology +## Topology +All Bluetooth Hands-Free devices support both capture and render. The audio driver should expose a kernel streaming (KS) topology for the Hands-Free device, as shown in the following diagram, to support both render and capture. -All Bluetooth Hands-Free devices support both capture and render. So the audio driver should expose a kernel streaming (KS) topology for the Hands-Free device as shown in the following diagram, to support both render and capture. +![Diagram showing the KS topology that the audio driver exposes for the hands-free device, to support render and capture.](images/btth-bypass-topology.png) -![diagram showing the ks topology that the audio driver exposes for the hands-free device, to support render and capture.](images/btth-bypass-topology.png) +**Note:** The audio driver developer can choose whether to implement a single filter for both capture and render paths or separate filters. However, the HFP device only allows a single file object on the GUID_DEVINTERFACE_BLUETOOTH_HFP_SCO_HCIBYPASS device interface. Therefore, a design that uses two filters needs to allow both filters to share the single file object. -**Note**  The audio driver developer can choose whether or not to implement a single filter for both capture and render paths, or separate filters. However, the HFP device only allows a single file object on the GUID\_DEVINTERFACE\_BLUETOOTH\_HFP\_SCO\_HCIBYPASS device interface. Therefore a design that uses two filters needs to allow both filters to share the single file object. +The DAC and ADC nodes represent the analog/digital conversions but don't support any KS properties. - +The volume nodes support [**KSPROPERTY_AUDIO_VOLUMELEVEL**](./ksproperty-audio-volumelevel.md) and [**KSEVENT_CONTROL_CHANGE**](./ksevent-control-change.md) by sending the SETVOLUME and GETVOLUMESTATUSUPDATE IOCTLs to the HFP driver. -The DAC and ADC nodes represent the analog/digital conversions, but do not support any KS properties. +The volume node should be implemented as follows: -The volume nodes support [**KSPROPERTY\_AUDIO\_VOLUMELEVEL**](./ksproperty-audio-volumelevel.md) and [**KSEVENT\_CONTROL\_CHANGE**](./ksevent-control-change.md) by sending the SETVOLUME and GETVOLUMESTATUSUPDATE IOCTLs to the HFP driver. +- If the Bluetooth headset supports volume control, the audio driver should include a volume node in its KS topology. The audio driver's volume property handlers send the above IOCLTs to the Bluetooth HFP driver to handle the volume. +- If the Bluetooth headset doesn't implement a hardware volume, and the codec (or DSP) has a hardware volume, the audio driver should handle the volume control on the codec (or DSP). +- If neither the Bluetooth headset nor the audio device have hardware volume controls, no volume node should be presented, and Windows will insert a software volume control node. +- The mute node is optional. The audio driver should implement the mute node if and only if the DSP or audio codec provides the capability to mute the bypass PCM signal before passing it to the Bluetooth controller. The mute nodes support [**KSPROPERTY_AUDIO_MUTE**](./ksproperty-audio-mute.md). -The volume node should be implemented as follows: +## Property requests -- If the Bluetooth headset supports volume control, then the audio driver should include a volume node in its KS topology. The audio driver's volume property handlers send the above IOCLTs to the Bluetooth HFP driver to handle the volume. +The audio driver uses the following KS properties to obtain information about any audio jack or jacks in the audio path. The audio driver can also use the appropriate property request to make or break a connection to any Bluetooth audio device in the audio path. -- If the Bluetooth headset does not implement a hardware volume, and the codec (or DSP) has a hardware volume, the audio driver should handle the volume control on the codec (or DSP). +**KSPROPERTY_JACK_DESCRIPTION** -- If the Bluetooth headset and the audio device do not have hardware volume controls, no volume node should be presented and Windows will insert a software volume control node. +This property returns a [**KSJACK_DESCRIPTION**](./ksjack-description.md) structure. The audio driver should set the [**KSPROPERTY_JACK_DESCRIPTION**](./ksproperty-jack-description.md) fields as follows. -The mute node is optional. The audio driver should implement the mute node, if and only if the DSP or audio codec provides the capability to mute the bypass PCM signal before passing it to the Bluetooth controller. The mute nodes support [**KSPROPERTY\_AUDIO\_MUTE**](./ksproperty-audio-mute.md). +- ChannelMapping = KSAUDIO_SPEAKER_MONO +- Color = 0 +- ConnectionType = eConnTypeOtherDigital +- GeoLocation = eGeoLocNotApplicable +- GenLocation = eGenLocOther +- PortConnection = ePortConnUnknown +- IsConnected = <*BOOL for current connection status*> -## Property requests +**KSPROPERTY_JACK_DESCRIPTION2** +This property returns a [**KSJACK_DESCRIPTION2**](./ksjack-description2.md) structure. The audio driver should set the [**KSPROPERTY_JACK_DESCRIPTION2**](./ksproperty-jack-description2.md) fields as follows. -The audio driver uses the following KS properties to obtain information about any audio jack or jacks in the audio path. And the audio driver can also use the appropriate property request to make or break a connection to any Bluetooth audio device in the audio path. +- DeviceStateInfo = 0 +- JackCapabilities = JACKDESC2_PRESENCE_DETECT_CAPABILITY -**KSPROPERTY\_JACK\_DESCRIPTION** +**KSPROPERTY_ONESHOT_RECONNECT** -This property returns a [**KSJACK\_DESCRIPTION**](./ksjack-description.md) structure. The audio driver should set the [**KSPROPERTY\_JACK\_DESCRIPTION**](./ksproperty-jack-description.md) fields as follows. -ChannelMapping = KSAUDIO\_SPEAKER\_MONO -Color = 0 -ConnectionType = eConnTypeOtherDigital -GeoLocation = eGeoLocNotApplicable -GenLocation = eGenLocOther -PortConnection = ePortConnUnknown -IsConnected = <*BOOL for current connection status*> -**KSPROPERTY\_JACK\_DESCRIPTION2** +The audio driver’s filter should support [**KSPROPERTY_ONESHOT_RECONNECT**](./ksproperty-oneshot-reconnect.md). To create and initialize this structure, the audio driver sends [**IOCTL_BTHHFP_DEVICE_REQUEST_CONNECT**](/windows-hardware/drivers/ddi/bthhfpddi/ni-bthhfpddi-ioctl_bthhfp_device_request_connect) to the HFP driver. The HFP driver completes this request and then attempts to connect to the Bluetooth audio device asynchronously. -This property returns a [**KSJACK\_DESCRIPTION2**](./ksjack-description2.md) structure. The audio driver should set the [**KSPROPERTY\_JACK\_DESCRIPTION2**](./ksproperty-jack-description2.md) fields as follows. -DeviceStateInfo = 0 -JackCapabilities = JACKDESC2\_PRESENCE\_DETECT\_CAPABILITY -**KSPROPERTY\_ONESHOT\_RECONNECT** +**KSPROPERTY_ONESHOT_DISCONNECT** -The audio driver’s filter should support [**KSPROPERTY\_ONESHOT\_RECONNECT**](./ksproperty-oneshot-reconnect.md). To create and initialize this structure, the audio driver sends [**IOCTL\_BTHHFP\_DEVICE\_REQUEST\_CONNECT**](/windows-hardware/drivers/ddi/bthhfpddi/ni-bthhfpddi-ioctl_bthhfp_device_request_connect) to the HFP driver. The HFP driver completes this request, and then attempts to connect to the Bluetooth audio device asynchronously. -**KSPROPERTY\_ONESHOT\_DISCONNECT** +The audio driver’s filter should support [**KSPROPERTY_ONESHOT_DISCONNECT**](./ksproperty-oneshot-disconnect.md). To create and initialize this structure, the audio driver sends [**IOCTL_BTHHFP_DEVICE_REQUEST_DISCONNECT**](/windows-hardware/drivers/ddi/bthhfpddi/ni-bthhfpddi-ioctl_bthhfp_device_request_disconnect) to the HFP driver. The HFP driver completes this request and then attempts to disconnect from the Bluetooth audio device asynchronously. -The audio driver’s filter should support [**KSPROPERTY\_ONESHOT\_DISCONNECT**](./ksproperty-oneshot-disconnect.md). To create and initialize this structure, the audio driver sends [**IOCTL\_BTHHFP\_DEVICE\_REQUEST\_DISCONNECT**](/windows-hardware/drivers/ddi/bthhfpddi/ni-bthhfpddi-ioctl_bthhfp_device_request_disconnect) to the HFP driver. The HFP driver completes this request, and then attempts to disconnect from the Bluetooth audio device asynchronously. When an audio driver supports these properties, the Sound dialog box in the Control Panel exposes Connect and Disconnect commands for the HFP endpoint. -## Related topics -[Theory of Operation](theory-of-operation.md) +## Related topics + +[Theory of Bluetooth bypass audio streaming](theory-of-operation.md) diff --git a/windows-driver-docs-pr/audio/ks-h.md b/windows-driver-docs-pr/audio/ks-h.md index 0490e7eb43..5f39cf2b5e 100644 --- a/windows-driver-docs-pr/audio/ks-h.md +++ b/windows-driver-docs-pr/audio/ks-h.md @@ -1,7 +1,8 @@ --- title: Ks.h description: This section contains reference topics for the Ks.h header. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- # Ks.h diff --git a/windows-driver-docs-pr/audio/ksevent-control-change.md b/windows-driver-docs-pr/audio/ksevent-control-change.md index 6a5acb35b8..69ec74e56b 100644 --- a/windows-driver-docs-pr/audio/ksevent-control-change.md +++ b/windows-driver-docs-pr/audio/ksevent-control-change.md @@ -4,13 +4,14 @@ description: The KSEVENT\_CONTROL\_CHANGE event indicates that a change in contr keywords: ["KSEVENT_CONTROL_CHANGE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSEVENT_CONTROL_CHANGE api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- # KSEVENT\_CONTROL\_CHANGE diff --git a/windows-driver-docs-pr/audio/ksevent-loopedstreaming-position.md b/windows-driver-docs-pr/audio/ksevent-loopedstreaming-position.md index 38a4d4d097..438db1ba01 100644 --- a/windows-driver-docs-pr/audio/ksevent-loopedstreaming-position.md +++ b/windows-driver-docs-pr/audio/ksevent-loopedstreaming-position.md @@ -4,15 +4,17 @@ description: The KSEVENT\_LOOPEDSTREAMING\_POSITION event indicates that the aud keywords: ["KSEVENT_LOOPEDSTREAMING_POSITION Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSEVENT_LOOPEDSTREAMING_POSITION api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSEVENT\_LOOPEDSTREAMING\_POSITION diff --git a/windows-driver-docs-pr/audio/ksevent-pincaps-formatchange.md b/windows-driver-docs-pr/audio/ksevent-pincaps-formatchange.md index e1be73f7a0..6dd088a9d3 100644 --- a/windows-driver-docs-pr/audio/ksevent-pincaps-formatchange.md +++ b/windows-driver-docs-pr/audio/ksevent-pincaps-formatchange.md @@ -4,15 +4,17 @@ description: The KSEVENT\_PINCAPS\_FORMATCHANGE event indicates to the audio sta keywords: ["KSEVENT_PINCAPS_FORMATCHANGE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSEVENT_PINCAPS_FORMATCHANGE api_location: - Ks.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSEVENT\_PINCAPS\_FORMATCHANGE diff --git a/windows-driver-docs-pr/audio/ksevent-pincaps-jackinfochange.md b/windows-driver-docs-pr/audio/ksevent-pincaps-jackinfochange.md index bc40788e10..1ad73f90c5 100644 --- a/windows-driver-docs-pr/audio/ksevent-pincaps-jackinfochange.md +++ b/windows-driver-docs-pr/audio/ksevent-pincaps-jackinfochange.md @@ -4,15 +4,17 @@ description: The KSEVENT\_PINCAPS\_JACKINFOCHANGE event indicates to the audio s keywords: ["KSEVENT_PINCAPS_JACKINFOCHANGE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSEVENT_PINCAPS_JACKINFOCHANGE api_location: - Ks.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSEVENT\_PINCAPS\_JACKINFOCHANGE diff --git a/windows-driver-docs-pr/audio/ksevent-sounddetector-matchdetected.md b/windows-driver-docs-pr/audio/ksevent-sounddetector-matchdetected.md index 47babc1de2..a6f2adf8cb 100644 --- a/windows-driver-docs-pr/audio/ksevent-sounddetector-matchdetected.md +++ b/windows-driver-docs-pr/audio/ksevent-sounddetector-matchdetected.md @@ -4,15 +4,17 @@ description: The KSEVENT\_SOUNDDETECTOR\_MATCHDETECTED event is generated by the keywords: ["KSEVENT_SOUNDDETECTOR_MATCHDETECTED Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSEVENT_SOUNDDETECTOR_MATCHDETECTED api_location: - ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSEVENT\_SOUNDDETECTOR\_MATCHDETECTED diff --git a/windows-driver-docs-pr/audio/ksevent-volumelimit-changed.md b/windows-driver-docs-pr/audio/ksevent-volumelimit-changed.md index a8ecfa7db3..1e26f1e790 100644 --- a/windows-driver-docs-pr/audio/ksevent-volumelimit-changed.md +++ b/windows-driver-docs-pr/audio/ksevent-volumelimit-changed.md @@ -4,13 +4,15 @@ description: The KSEVENT\_VOLUMELIMIT\_CHANGED event indicates to the audio stac keywords: ["KSEVENT_VOLUMELIMIT_CHANGED Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSEVENT_VOLUMELIMIT_CHANGED api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSEVENT\_VOLUMELIMIT\_CHANGED diff --git a/windows-driver-docs-pr/audio/kseventsetid-audiocontrolchange.md b/windows-driver-docs-pr/audio/kseventsetid-audiocontrolchange.md index 83ceae7d67..7523149e15 100644 --- a/windows-driver-docs-pr/audio/kseventsetid-audiocontrolchange.md +++ b/windows-driver-docs-pr/audio/kseventsetid-audiocontrolchange.md @@ -2,9 +2,10 @@ title: KSEVENTSETID\_AudioControlChange description: KSEVENTSETID\_AudioControlChange keywords: ["KSEVENTSETID_AudioControlChange"] -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSEVENTSETID\_AudioControlChange diff --git a/windows-driver-docs-pr/audio/kseventsetid-loopedstreaming.md b/windows-driver-docs-pr/audio/kseventsetid-loopedstreaming.md index 1edf023002..9719fb6f2c 100644 --- a/windows-driver-docs-pr/audio/kseventsetid-loopedstreaming.md +++ b/windows-driver-docs-pr/audio/kseventsetid-loopedstreaming.md @@ -2,7 +2,7 @@ title: KSEVENTSETID\_LoopedStreaming description: KSEVENTSETID\_LoopedStreaming keywords: ["KSEVENTSETID_LoopedStreaming"] -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- # KSEVENTSETID\_LoopedStreaming diff --git a/windows-driver-docs-pr/audio/kseventsetid-pincapschange.md b/windows-driver-docs-pr/audio/kseventsetid-pincapschange.md index 557804dd0e..10699b2b66 100644 --- a/windows-driver-docs-pr/audio/kseventsetid-pincapschange.md +++ b/windows-driver-docs-pr/audio/kseventsetid-pincapschange.md @@ -1,9 +1,10 @@ --- title: KSEVENTSETID\_PinCapsChange description: KSEVENTSETID\_PinCapsChange -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSEVENTSETID\_PinCapsChange diff --git a/windows-driver-docs-pr/audio/kseventsetid-sounddetector.md b/windows-driver-docs-pr/audio/kseventsetid-sounddetector.md index c5c16c1409..d63183b955 100644 --- a/windows-driver-docs-pr/audio/kseventsetid-sounddetector.md +++ b/windows-driver-docs-pr/audio/kseventsetid-sounddetector.md @@ -1,9 +1,10 @@ --- title: KSEVENTSETID\_SoundDetector description: The KSEVENTSETID\_SoundDetector event set is used by audio drivers to notify the operating system that the sound detector has detected a match. -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSEVENTSETID\_SoundDetector diff --git a/windows-driver-docs-pr/audio/kseventsetid-volumelimit.md b/windows-driver-docs-pr/audio/kseventsetid-volumelimit.md index 4a00e69a0d..50a26b4f75 100644 --- a/windows-driver-docs-pr/audio/kseventsetid-volumelimit.md +++ b/windows-driver-docs-pr/audio/kseventsetid-volumelimit.md @@ -1,9 +1,10 @@ --- title: KSEVENTSETID\_VolumeLimit description: The KSEVENTSETID\_VolumeLimit event set has been introduced with Windows 8.1. -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSEVENTSETID\_VolumeLimit diff --git a/windows-driver-docs-pr/audio/ksjack-description.md b/windows-driver-docs-pr/audio/ksjack-description.md index a93b67ce3b..70f65ba479 100644 --- a/windows-driver-docs-pr/audio/ksjack-description.md +++ b/windows-driver-docs-pr/audio/ksjack-description.md @@ -4,15 +4,17 @@ description: The KSJACK\_DESCRIPTION structure specifies the physical attributes keywords: ["KSJACK_DESCRIPTION structure Audio Devices", "PKSJACK_DESCRIPTION structure pointer Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSJACK_DESCRIPTION api_location: - ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSJACK\_DESCRIPTION structure @@ -20,7 +22,7 @@ The KSJACK\_DESCRIPTION structure specifies the physical attributes of an audio ## Syntax -```ManagedCPlusPlus +```cpp typedef struct { DWORD              ChannelMapping; DWORD              Color; @@ -290,6 +292,10 @@ When an audio device does not expose a physically accessible jack, the audio dev [**KSPROPERTY\_JACK\_DESCRIPTION**](ksproperty-jack-description.md) +[**KSPROPERTY\_JACK\_DESCRIPTION2**](ksproperty-jack-description2.md) + +[**KSPROPERTY\_JACK\_DESCRIPTION3**](ksproperty-jack-description3.md) + diff --git a/windows-driver-docs-pr/audio/ksjack-description2.md b/windows-driver-docs-pr/audio/ksjack-description2.md index 448bbb5868..afacc00ec1 100644 --- a/windows-driver-docs-pr/audio/ksjack-description2.md +++ b/windows-driver-docs-pr/audio/ksjack-description2.md @@ -4,15 +4,17 @@ description: The KSJACK\_DESCRIPTION2 structure specifies the capabilities and t keywords: ["KSJACK_DESCRIPTION2 structure Audio Devices", "PKSJACK_DESCRIPTION2 structure pointer Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSJACK_DESCRIPTION2 api_location: - ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSJACK\_DESCRIPTION2 structure @@ -20,7 +22,7 @@ The `KSJACK_DESCRIPTION2` structure specifies the capabilities and the current s ## Syntax -```ManagedCPlusPlus +```cpp typedef struct _tagKSJACK_DESCRIPTION2 { DWORD DeviceStateInfo; DWORD JackCapabilities; diff --git a/windows-driver-docs-pr/audio/ksjack-description3.md b/windows-driver-docs-pr/audio/ksjack-description3.md new file mode 100644 index 0000000000..e62093cb18 --- /dev/null +++ b/windows-driver-docs-pr/audio/ksjack-description3.md @@ -0,0 +1,87 @@ +--- +title: KSJACK\_DESCRIPTION3 structure +description: The KSJACK\_DESCRIPTION3 structure specifies the capabilities and the current state of a jack that supports jack presence detection. +keywords: ["KSJACK_DESCRIPTION3 structure Audio Devices", "PKSJACK_DESCRIPTION3 structure pointer Audio Devices"] +topic_type: +- apiref +ms.topic: reference +api_name: +- KSJACK_DESCRIPTION3 +api_location: +- ksmedia.h +api_type: +- HeaderDef +ms.date: 10/26/2022 +--- + +# KSJACK\_DESCRIPTION3 structure + +In version 22H2 and later Windows operating systems, the `KSJACK_DESCRIPTION3` structure can be used to specify and change the current configuration of the jack. + +## Syntax + +```cpp +typedef struct _tagKSJACK_DESCRIPTION3 +{ + ULONG ConfigId; + +} KSJACK_DESCRIPTION3, *PKSJACK_DESCRIPTION3; +``` + +## Members + +**ConfigId** + +Driver defined bitmask or enum describing the current configuration, changing this value causes +audioendpointbuilder to refresh the cache to ensure that the published endpoint matches the current config. + +## Remarks + +### Using KSJACK\_DESCRIPTION3 to communicate audio device changes + +The Windows audio system caches audio device capabilities during audio endpoint creation. These cached values are for capabilities such as the presence of a HW audio engine, format support, container ID, buffer size characteristics, etc. These cached values are retained for the life of the windows installation. They are refreshed only when the audio driver is updated or during an OS upgrade. + +With **KSJACK\_DESCRIPTION3**, the Windows audio system provides a mechanism for the audio driver to request all cached values be discarded and refreshed. The request can be triggered by changes in the audio device capabilities such as resource constraints. + +Whenever the driver changes the contents of **KSJACK\_DESCRIPTION3** at runtime, the driver will trigger the existing [KSEVENT_PINCAPS_JACKINFOCHANGE](ksproperty-jack-description3.md) event. + +The Windows audio system maintains the last reported *ConfigId* value cached on the audio endpoint. The *ConfigId* value is retrieved in response to [KSEVENT_PINCAPS_JACKINFOCHANGE](ksproperty-jack-description3.md) event and during normal processing of the audio endpoint at system boot, Audio Endpoint Builder service restart, audio driver update, or interface state changes for the endpoint. + +If the retrieved *ConfigId* value differs from the previously stored value, the Windows audio system will discard all previously cached endpoint capabilities and refresh them. + +The recommended usage is to define multiple audio endpoint configurations within the driver that is controlled by the *ConfigId* (bitmask or enum) value. For example, *ConfigId* of 1 may indicate the presence of an audio engine node, whereas *ConfigId* 2 would not report an audio engine node. The *ConfigId* in use by the driver is shared with the Windows audio system through [**KSPROPERTY_JACK_DESCRIPTION3**](ksproperty-jack-description3.md) and acts to synchronize the endpoint with the capabilities cached by the Windows audio system. + +The value of the *ConfigId* is opaque to Windows. The audio driver could use a timestamp or incrementing value chosen at run time in place of a bitmask or enum as suggested above. This strategy is not recommended as it may result in unnecessary endpoint refreshes during boot up or interface changes to synchronize the last stored *ConfigId* value to the newly reported value, even when the endpoint capabilities are unchanged. This approach may also increase the chances of the driver and Windows becoming out of sync, which can result in audio playback failures. + +The mechanism used to refresh the cached values on the endpoint when the *ConfigId* changes is the same as used for Operating System Upgrades and Driver Updates. A new endpoint with a different ID is created which will contain the refreshed cached values that match the new *ConfigId* settings for the endpoint, user settings are then copied from the old endpoint to the new endpoint, and finally the old endpoint is deleted. For more information, on the audio endpoint migration process in OS upgrades, see [Operating System Upgrades](operating-system-upgrades.md). + +## Requirements + + ++++ + + + + + + + + + + +

Version

Available in version 22H2 and later Windows operating systems.

Header

Ksmedia.h (include Ksmedia.h)
+ +## See also + +[**KSJACK\_DESCRIPTION**](ksjack-description.md) + +[**KSPROPERTY_JACK_DESCRIPTION3**](ksproperty-jack-description3.md) + +[**IKsJackDescription2::GetJackDescription2**](/windows/win32/api/devicetopology/nf-devicetopology-iksjackdescription2-getjackdescription2) + +[Dynamic Format Change](./dynamic-format-change.md) + +[Operating System Upgrades](operating-system-upgrades.md) diff --git a/windows-driver-docs-pr/audio/ksmedia-h.md b/windows-driver-docs-pr/audio/ksmedia-h.md index 124abb24fd..f969c0c09e 100644 --- a/windows-driver-docs-pr/audio/ksmedia-h.md +++ b/windows-driver-docs-pr/audio/ksmedia-h.md @@ -1,7 +1,7 @@ --- title: Ksmedia.h description: This section contains reference topics for the Ksmedia.h header. -ms.date: 11/27/2018 +ms.date: 10/24/2022 --- # Ksmedia.h @@ -125,6 +125,7 @@ This section contains reference topics for the Ksmedia.h header. |[KSPROPERTY_JACK_CONTAINERID](ksproperty-jack-containerid.md)|The KSPROPERTY_JACK_CONTAINERID property is implemented as a pin-wise property that is accessed by using the filter handle.| |[KSPROPERTY_JACK_DESCRIPTION](ksproperty-jack-description.md)|The KSPROPERTY_JACK_DESCRIPTION property is implemented as a multi-item, pin-wise property that is accessed through the filter handle.| |[KSPROPERTY_JACK_DESCRIPTION2](ksproperty-jack-description2.md)|The KSPROPERTY_JACK_DESCRIPTION2 property is implemented as a pin-wise property that is accessed by using the filter handle.| +|[KSPROPERTY_JACK_DESCRIPTION3](ksproperty-jack-description3.md)|The KSPROPERTY_JACK_DESCRIPTION3 property is implemented as a pin-wise property that is accessed by using the filter handle.| |[KSPROPERTY_JACK_SINK_INFO](ksproperty-jack-sink-info.md)|The KSPROPERTY_JACK_SINK_INFO property is implemented as a pin-wise property that is accessed by using the filter handle.| |[KSPROPERTY_ONESHOT_DISCONNECT](ksproperty-oneshot-disconnect.md)|The KSPROPERTY_ONESHOT_DISCONNECT property is used to prompt the audio driver to disconnect from the Bluetooth audio device.| |[KSPROPERTY_ONESHOT_RECONNECT](ksproperty-oneshot-reconnect.md)|The KSPROPERTY_ONESHOT_RECONNECT property is used to prompt the audio driver to attempt to connect to the Bluetooth audio device.| diff --git a/windows-driver-docs-pr/audio/ksnodetype-3d-effects.md b/windows-driver-docs-pr/audio/ksnodetype-3d-effects.md index 00c394fef4..d1bad9dfc2 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-3d-effects.md +++ b/windows-driver-docs-pr/audio/ksnodetype-3d-effects.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_3D\_EFFECTS keywords: ["KSNODETYPE_3D_EFFECTS Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_3D_EFFECTS api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_3D\_EFFECTS diff --git a/windows-driver-docs-pr/audio/ksnodetype-acoustic-echo-cancel.md b/windows-driver-docs-pr/audio/ksnodetype-acoustic-echo-cancel.md index a949f9ac40..d177307be4 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-acoustic-echo-cancel.md +++ b/windows-driver-docs-pr/audio/ksnodetype-acoustic-echo-cancel.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_ACOUSTIC\_ECHO\_CANCEL keywords: ["KSNODETYPE_ACOUSTIC_ECHO_CANCEL Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_ACOUSTIC_ECHO_CANCEL api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_ACOUSTIC\_ECHO\_CANCEL diff --git a/windows-driver-docs-pr/audio/ksnodetype-adc.md b/windows-driver-docs-pr/audio/ksnodetype-adc.md index f7b1ce462e..3b7ec21cd6 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-adc.md +++ b/windows-driver-docs-pr/audio/ksnodetype-adc.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_ADC keywords: ["KSNODETYPE_ADC Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_ADC api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_ADC diff --git a/windows-driver-docs-pr/audio/ksnodetype-agc.md b/windows-driver-docs-pr/audio/ksnodetype-agc.md index 7db762297c..a5d9508443 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-agc.md +++ b/windows-driver-docs-pr/audio/ksnodetype-agc.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_AGC keywords: ["KSNODETYPE_AGC Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_AGC api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_AGC diff --git a/windows-driver-docs-pr/audio/ksnodetype-audio-engine.md b/windows-driver-docs-pr/audio/ksnodetype-audio-engine.md index ca2ae4d9de..e63c16a1c1 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-audio-engine.md +++ b/windows-driver-docs-pr/audio/ksnodetype-audio-engine.md @@ -4,13 +4,15 @@ description: The KSNODETYPE\_AUDIO\_ENGINE audio endpoint is a new endpoint that keywords: ["KSNODETYPE_AUDIO_ENGINE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_AUDIO_ENGINE api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_AUDIO\_ENGINE diff --git a/windows-driver-docs-pr/audio/ksnodetype-audio-keyworddetector.md b/windows-driver-docs-pr/audio/ksnodetype-audio-keyworddetector.md index 29f6995578..a91255ebae 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-audio-keyworddetector.md +++ b/windows-driver-docs-pr/audio/ksnodetype-audio-keyworddetector.md @@ -4,13 +4,15 @@ description: The KSNODETYPE\_AUDIO\_KEYWORDDETECTOR audio endpoint is a new endp keywords: ["KSNODETYPE_AUDIO_KEYWORDDETECTOR Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_AUDIO_KEYWORDDETECTOR api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_AUDIO\_KEYWORDDETECTOR diff --git a/windows-driver-docs-pr/audio/ksnodetype-chorus.md b/windows-driver-docs-pr/audio/ksnodetype-chorus.md index 058b26114e..9bbf9da3cb 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-chorus.md +++ b/windows-driver-docs-pr/audio/ksnodetype-chorus.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_CHORUS keywords: ["KSNODETYPE_CHORUS Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_CHORUS api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_CHORUS diff --git a/windows-driver-docs-pr/audio/ksnodetype-dac.md b/windows-driver-docs-pr/audio/ksnodetype-dac.md index 1c299ce716..94a163d2af 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-dac.md +++ b/windows-driver-docs-pr/audio/ksnodetype-dac.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_DAC keywords: ["KSNODETYPE_DAC Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_DAC api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_DAC diff --git a/windows-driver-docs-pr/audio/ksnodetype-delay.md b/windows-driver-docs-pr/audio/ksnodetype-delay.md index 2171cce779..25275ce420 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-delay.md +++ b/windows-driver-docs-pr/audio/ksnodetype-delay.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_DELAY keywords: ["KSNODETYPE_DELAY Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_DELAY api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_DELAY diff --git a/windows-driver-docs-pr/audio/ksnodetype-demux.md b/windows-driver-docs-pr/audio/ksnodetype-demux.md index 94ebaab616..3886428754 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-demux.md +++ b/windows-driver-docs-pr/audio/ksnodetype-demux.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_DEMUX keywords: ["KSNODETYPE_DEMUX Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_DEMUX api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_DEMUX diff --git a/windows-driver-docs-pr/audio/ksnodetype-dev-specific.md b/windows-driver-docs-pr/audio/ksnodetype-dev-specific.md index 737f314884..2159d2d579 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-dev-specific.md +++ b/windows-driver-docs-pr/audio/ksnodetype-dev-specific.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_DEV\_SPECIFIC keywords: ["KSNODETYPE_DEV_SPECIFIC Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_DEV_SPECIFIC api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_DEV\_SPECIFIC diff --git a/windows-driver-docs-pr/audio/ksnodetype-dmsynth-caps.md b/windows-driver-docs-pr/audio/ksnodetype-dmsynth-caps.md index 434de7078c..8977a8eb17 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-dmsynth-caps.md +++ b/windows-driver-docs-pr/audio/ksnodetype-dmsynth-caps.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_DMSYNTH\_CAPS keywords: ["KSNODETYPE_DMSYNTH_CAPS Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_DMSYNTH_CAPS api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_DMSYNTH\_CAPS diff --git a/windows-driver-docs-pr/audio/ksnodetype-dmsynth.md b/windows-driver-docs-pr/audio/ksnodetype-dmsynth.md index b47534e03e..53efc48065 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-dmsynth.md +++ b/windows-driver-docs-pr/audio/ksnodetype-dmsynth.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_DMSYNTH keywords: ["KSNODETYPE_DMSYNTH Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_DMSYNTH api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_DMSYNTH diff --git a/windows-driver-docs-pr/audio/ksnodetype-drm-descramble.md b/windows-driver-docs-pr/audio/ksnodetype-drm-descramble.md index 286fb31cc2..5b318f627a 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-drm-descramble.md +++ b/windows-driver-docs-pr/audio/ksnodetype-drm-descramble.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_DRM\_DESCRAMBLE keywords: ["KSNODETYPE_DRM_DESCRAMBLE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_DRM_DESCRAMBLE api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_DRM\_DESCRAMBLE diff --git a/windows-driver-docs-pr/audio/ksnodetype-equalizer.md b/windows-driver-docs-pr/audio/ksnodetype-equalizer.md index 39cf032f14..f4ebdf89e6 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-equalizer.md +++ b/windows-driver-docs-pr/audio/ksnodetype-equalizer.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_EQUALIZER keywords: ["KSNODETYPE_EQUALIZER Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_EQUALIZER api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_EQUALIZER diff --git a/windows-driver-docs-pr/audio/ksnodetype-fm-rx.md b/windows-driver-docs-pr/audio/ksnodetype-fm-rx.md index 733f469c10..fbf74c6c3b 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-fm-rx.md +++ b/windows-driver-docs-pr/audio/ksnodetype-fm-rx.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_FM\_RX keywords: ["KSNODETYPE_FM_RX Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_FM_RX api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_FM\_RX diff --git a/windows-driver-docs-pr/audio/ksnodetype-loudness.md b/windows-driver-docs-pr/audio/ksnodetype-loudness.md index a2812953c5..9d62159e7b 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-loudness.md +++ b/windows-driver-docs-pr/audio/ksnodetype-loudness.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_LOUDNESS keywords: ["KSNODETYPE_LOUDNESS Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_LOUDNESS api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_LOUDNESS diff --git a/windows-driver-docs-pr/audio/ksnodetype-microphone-array-processor.md b/windows-driver-docs-pr/audio/ksnodetype-microphone-array-processor.md index fbc97b4068..496e50ad11 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-microphone-array-processor.md +++ b/windows-driver-docs-pr/audio/ksnodetype-microphone-array-processor.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_MICROPHONE\_ARRAY\_PROCESSOR keywords: ["KSNODETYPE_MICROPHONE_ARRAY_PROCESSOR Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_MICROPHONE_ARRAY_PROCESSOR api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_MICROPHONE\_ARRAY\_PROCESSOR diff --git a/windows-driver-docs-pr/audio/ksnodetype-mute.md b/windows-driver-docs-pr/audio/ksnodetype-mute.md index 760ff61622..b71f08e282 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-mute.md +++ b/windows-driver-docs-pr/audio/ksnodetype-mute.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_MUTE keywords: ["KSNODETYPE_MUTE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_MUTE api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_MUTE diff --git a/windows-driver-docs-pr/audio/ksnodetype-mux.md b/windows-driver-docs-pr/audio/ksnodetype-mux.md index bbee65d084..8547f34c65 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-mux.md +++ b/windows-driver-docs-pr/audio/ksnodetype-mux.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_MUX keywords: ["KSNODETYPE_MUX Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_MUX api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_MUX diff --git a/windows-driver-docs-pr/audio/ksnodetype-noise-suppress.md b/windows-driver-docs-pr/audio/ksnodetype-noise-suppress.md index ff33c5c852..e703a2b84e 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-noise-suppress.md +++ b/windows-driver-docs-pr/audio/ksnodetype-noise-suppress.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_NOISE\_SUPPRESS keywords: ["KSNODETYPE_NOISE_SUPPRESS Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_NOISE_SUPPRESS api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_NOISE\_SUPPRESS diff --git a/windows-driver-docs-pr/audio/ksnodetype-peakmeter.md b/windows-driver-docs-pr/audio/ksnodetype-peakmeter.md index 71228c6b60..5e56b660dd 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-peakmeter.md +++ b/windows-driver-docs-pr/audio/ksnodetype-peakmeter.md @@ -4,6 +4,7 @@ description: KSNODETYPE\_PEAKMETER keywords: ["KSNODETYPE_PEAKMETER Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_PEAKMETER api_type: diff --git a/windows-driver-docs-pr/audio/ksnodetype-prologic-decoder.md b/windows-driver-docs-pr/audio/ksnodetype-prologic-decoder.md index 31e8346cfb..32c31a1cde 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-prologic-decoder.md +++ b/windows-driver-docs-pr/audio/ksnodetype-prologic-decoder.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_PROLOGIC\_DECODER keywords: ["KSNODETYPE_PROLOGIC_DECODER Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_PROLOGIC_DECODER api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_PROLOGIC\_DECODER diff --git a/windows-driver-docs-pr/audio/ksnodetype-prologic-encoder.md b/windows-driver-docs-pr/audio/ksnodetype-prologic-encoder.md index 0db6c65eaf..2f52bbe01a 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-prologic-encoder.md +++ b/windows-driver-docs-pr/audio/ksnodetype-prologic-encoder.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_PROLOGIC\_ENCODER keywords: ["KSNODETYPE_PROLOGIC_ENCODER Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_PROLOGIC_ENCODER api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_PROLOGIC\_ENCODER diff --git a/windows-driver-docs-pr/audio/ksnodetype-reverb.md b/windows-driver-docs-pr/audio/ksnodetype-reverb.md index 83a236a6d1..b2e74b45ec 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-reverb.md +++ b/windows-driver-docs-pr/audio/ksnodetype-reverb.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_REVERB keywords: ["KSNODETYPE_REVERB Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_REVERB api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_REVERB diff --git a/windows-driver-docs-pr/audio/ksnodetype-src.md b/windows-driver-docs-pr/audio/ksnodetype-src.md index 52a6a8354b..3dac804c65 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-src.md +++ b/windows-driver-docs-pr/audio/ksnodetype-src.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_SRC keywords: ["KSNODETYPE_SRC Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_SRC api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_SRC diff --git a/windows-driver-docs-pr/audio/ksnodetype-stereo-enhance.md b/windows-driver-docs-pr/audio/ksnodetype-stereo-enhance.md index 10a894aa9b..f04219cb78 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-stereo-enhance.md +++ b/windows-driver-docs-pr/audio/ksnodetype-stereo-enhance.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_STEREO\_ENHANCE keywords: ["KSNODETYPE_STEREO_ENHANCE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_STEREO_ENHANCE api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_STEREO\_ENHANCE diff --git a/windows-driver-docs-pr/audio/ksnodetype-stereo-wide.md b/windows-driver-docs-pr/audio/ksnodetype-stereo-wide.md index 5e084f505d..ae32d43abe 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-stereo-wide.md +++ b/windows-driver-docs-pr/audio/ksnodetype-stereo-wide.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_STEREO\_WIDE keywords: ["KSNODETYPE_STEREO_WIDE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_STEREO_WIDE api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_STEREO\_WIDE diff --git a/windows-driver-docs-pr/audio/ksnodetype-sum.md b/windows-driver-docs-pr/audio/ksnodetype-sum.md index ec082bc3a0..8aa3efd839 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-sum.md +++ b/windows-driver-docs-pr/audio/ksnodetype-sum.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_SUM keywords: ["KSNODETYPE_SUM Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_SUM api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_SUM diff --git a/windows-driver-docs-pr/audio/ksnodetype-supermix.md b/windows-driver-docs-pr/audio/ksnodetype-supermix.md index e3fc94b065..2d929c6786 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-supermix.md +++ b/windows-driver-docs-pr/audio/ksnodetype-supermix.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_SUPERMIX keywords: ["KSNODETYPE_SUPERMIX Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_SUPERMIX api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_SUPERMIX diff --git a/windows-driver-docs-pr/audio/ksnodetype-swmidi.md b/windows-driver-docs-pr/audio/ksnodetype-swmidi.md index 162e6b1fc1..a98500b423 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-swmidi.md +++ b/windows-driver-docs-pr/audio/ksnodetype-swmidi.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_SWMIDI keywords: ["KSNODETYPE_SWMIDI Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_SWMIDI api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_SWMIDI diff --git a/windows-driver-docs-pr/audio/ksnodetype-swsynth.md b/windows-driver-docs-pr/audio/ksnodetype-swsynth.md index 9e53e062b8..9e11dfd7c0 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-swsynth.md +++ b/windows-driver-docs-pr/audio/ksnodetype-swsynth.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_SWSYNTH keywords: ["KSNODETYPE_SWSYNTH Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_SWSYNTH api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_SWSYNTH diff --git a/windows-driver-docs-pr/audio/ksnodetype-synthesizer.md b/windows-driver-docs-pr/audio/ksnodetype-synthesizer.md index bd6b1817c0..71097cc0e4 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-synthesizer.md +++ b/windows-driver-docs-pr/audio/ksnodetype-synthesizer.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_SYNTHESIZER keywords: ["KSNODETYPE_SYNTHESIZER Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_SYNTHESIZER api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_SYNTHESIZER diff --git a/windows-driver-docs-pr/audio/ksnodetype-telephony-bidi.md b/windows-driver-docs-pr/audio/ksnodetype-telephony-bidi.md index 123a8e416c..5b41ffc64e 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-telephony-bidi.md +++ b/windows-driver-docs-pr/audio/ksnodetype-telephony-bidi.md @@ -4,13 +4,15 @@ description: The KSNODETYPE\_TELEPHONY\_BIDI node represents both sides (bi-dire keywords: ["KSNODETYPE_TELEPHONY_BIDI Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_TELEPHONY_BIDI api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_TELEPHONY\_BIDI diff --git a/windows-driver-docs-pr/audio/ksnodetype-tone.md b/windows-driver-docs-pr/audio/ksnodetype-tone.md index 65ca639a34..4d45ac2569 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-tone.md +++ b/windows-driver-docs-pr/audio/ksnodetype-tone.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_TONE keywords: ["KSNODETYPE_TONE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_TONE api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_TONE diff --git a/windows-driver-docs-pr/audio/ksnodetype-volume.md b/windows-driver-docs-pr/audio/ksnodetype-volume.md index cd2553db1d..787342afaa 100644 --- a/windows-driver-docs-pr/audio/ksnodetype-volume.md +++ b/windows-driver-docs-pr/audio/ksnodetype-volume.md @@ -4,13 +4,15 @@ description: KSNODETYPE\_VOLUME keywords: ["KSNODETYPE_VOLUME Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSNODETYPE_VOLUME api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSNODETYPE\_VOLUME diff --git a/windows-driver-docs-pr/audio/ksproperty-ac3-alternate-audio.md b/windows-driver-docs-pr/audio/ksproperty-ac3-alternate-audio.md index c90b15cfb4..8fc62d4f1a 100644 --- a/windows-driver-docs-pr/audio/ksproperty-ac3-alternate-audio.md +++ b/windows-driver-docs-pr/audio/ksproperty-ac3-alternate-audio.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AC3\_ALTERNATE\_AUDIO property specifies whether th keywords: ["KSPROPERTY_AC3_ALTERNATE_AUDIO Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AC3_ALTERNATE_AUDIO api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AC3\_ALTERNATE\_AUDIO diff --git a/windows-driver-docs-pr/audio/ksproperty-ac3-bit-stream-mode.md b/windows-driver-docs-pr/audio/ksproperty-ac3-bit-stream-mode.md index e86859448c..5cdfe69967 100644 --- a/windows-driver-docs-pr/audio/ksproperty-ac3-bit-stream-mode.md +++ b/windows-driver-docs-pr/audio/ksproperty-ac3-bit-stream-mode.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AC3\_BIT\_STREAM\_MODE property specifies the bit-s keywords: ["KSPROPERTY_AC3_BIT_STREAM_MODE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AC3_BIT_STREAM_MODE api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AC3\_BIT\_STREAM\_MODE diff --git a/windows-driver-docs-pr/audio/ksproperty-ac3-dialogue-level.md b/windows-driver-docs-pr/audio/ksproperty-ac3-dialogue-level.md index 8514ded5fe..39898e6031 100644 --- a/windows-driver-docs-pr/audio/ksproperty-ac3-dialogue-level.md +++ b/windows-driver-docs-pr/audio/ksproperty-ac3-dialogue-level.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AC3\_DIALOGUE\_LEVEL property specifies the average keywords: ["KSPROPERTY_AC3_DIALOGUE_LEVEL Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AC3_DIALOGUE_LEVEL api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AC3\_DIALOGUE\_LEVEL diff --git a/windows-driver-docs-pr/audio/ksproperty-ac3-downmix.md b/windows-driver-docs-pr/audio/ksproperty-ac3-downmix.md index f3b74c1b80..125e1253f4 100644 --- a/windows-driver-docs-pr/audio/ksproperty-ac3-downmix.md +++ b/windows-driver-docs-pr/audio/ksproperty-ac3-downmix.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AC3\_DOWNMIX property specifies whether the program keywords: ["KSPROPERTY_AC3_DOWNMIX Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AC3_DOWNMIX api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AC3\_DOWNMIX diff --git a/windows-driver-docs-pr/audio/ksproperty-ac3-error-concealment.md b/windows-driver-docs-pr/audio/ksproperty-ac3-error-concealment.md index 3f845c4eaa..0d5c156bb5 100644 --- a/windows-driver-docs-pr/audio/ksproperty-ac3-error-concealment.md +++ b/windows-driver-docs-pr/audio/ksproperty-ac3-error-concealment.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AC3\_ERROR\_CONCEALMENT property specifies the mann keywords: ["KSPROPERTY_AC3_ERROR_CONCEALMENT Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AC3_ERROR_CONCEALMENT api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AC3\_ERROR\_CONCEALMENT diff --git a/windows-driver-docs-pr/audio/ksproperty-ac3-language-code.md b/windows-driver-docs-pr/audio/ksproperty-ac3-language-code.md index b3f41a9232..6cae37863b 100644 --- a/windows-driver-docs-pr/audio/ksproperty-ac3-language-code.md +++ b/windows-driver-docs-pr/audio/ksproperty-ac3-language-code.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AC3\_LANGUAGE\_CODE property specifies the language keywords: ["KSPROPERTY_AC3_LANGUAGE_CODE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AC3_LANGUAGE_CODE api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AC3\_LANGUAGE\_CODE diff --git a/windows-driver-docs-pr/audio/ksproperty-ac3-room-type.md b/windows-driver-docs-pr/audio/ksproperty-ac3-room-type.md index 29e2b83e5f..c439eb38e7 100644 --- a/windows-driver-docs-pr/audio/ksproperty-ac3-room-type.md +++ b/windows-driver-docs-pr/audio/ksproperty-ac3-room-type.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AC3\_ROOM\_TYPE property specifies the type and cal keywords: ["KSPROPERTY_AC3_ROOM_TYPE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AC3_ROOM_TYPE api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AC3\_ROOM\_TYPE diff --git a/windows-driver-docs-pr/audio/ksproperty-aec-mode.md b/windows-driver-docs-pr/audio/ksproperty-aec-mode.md index 26416abbbd..5f0c5aa076 100644 --- a/windows-driver-docs-pr/audio/ksproperty-aec-mode.md +++ b/windows-driver-docs-pr/audio/ksproperty-aec-mode.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AEC\_MODE property is used to control an AEC node's keywords: ["KSPROPERTY_AEC_MODE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AEC_MODE api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AEC\_MODE diff --git a/windows-driver-docs-pr/audio/ksproperty-aec-noise-fill-enable.md b/windows-driver-docs-pr/audio/ksproperty-aec-noise-fill-enable.md index ddc17e8782..a9e7fc4dcf 100644 --- a/windows-driver-docs-pr/audio/ksproperty-aec-noise-fill-enable.md +++ b/windows-driver-docs-pr/audio/ksproperty-aec-noise-fill-enable.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AEC\_NOISE\_FILL\_ENABLE property is used to enable keywords: ["KSPROPERTY_AEC_NOISE_FILL_ENABLE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AEC_NOISE_FILL_ENABLE api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AEC\_NOISE\_FILL\_ENABLE diff --git a/windows-driver-docs-pr/audio/ksproperty-aec-status.md b/windows-driver-docs-pr/audio/ksproperty-aec-status.md index 9e7843744c..122681e390 100644 --- a/windows-driver-docs-pr/audio/ksproperty-aec-status.md +++ b/windows-driver-docs-pr/audio/ksproperty-aec-status.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AEC\_STATUS property is used to monitor the status keywords: ["KSPROPERTY_AEC_STATUS Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AEC_STATUS api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AEC\_STATUS diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-3d-interface.md b/windows-driver-docs-pr/audio/ksproperty-audio-3d-interface.md index 534301d4c6..26946256f5 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-3d-interface.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-3d-interface.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_3D\_INTERFACE property specifies the 3D algo keywords: ["KSPROPERTY_AUDIO_3D_INTERFACE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_3D_INTERFACE api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_3D\_INTERFACE diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-agc.md b/windows-driver-docs-pr/audio/ksproperty-audio-agc.md index bb5157b64f..cd621b6f7d 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-agc.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-agc.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_AGC property specifies the state of the AGC keywords: ["KSPROPERTY_AUDIO_AGC Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_AGC api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_AGC diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-algorithm-instance.md b/windows-driver-docs-pr/audio/ksproperty-audio-algorithm-instance.md index 3172c599e4..e6472e3f31 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-algorithm-instance.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-algorithm-instance.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_ALGORITHM\_INSTANCE property specifies the d keywords: ["KSPROPERTY_AUDIO_ALGORITHM_INSTANCE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_ALGORITHM_INSTANCE api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_ALGORITHM\_INSTANCE diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-bass-boost.md b/windows-driver-docs-pr/audio/ksproperty-audio-bass-boost.md index dd9a3bc9e8..95e0d6a58e 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-bass-boost.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-bass-boost.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_BASS\_BOOST property enables and disables ba keywords: ["KSPROPERTY_AUDIO_BASS_BOOST Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_BASS_BOOST api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_BASS\_BOOST diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-bass.md b/windows-driver-docs-pr/audio/ksproperty-audio-bass.md index 49b58096aa..081e3001e9 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-bass.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-bass.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_BASS property specifies the bass level for a keywords: ["KSPROPERTY_AUDIO_BASS Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_BASS api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_BASS diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-buffer-duration.md b/windows-driver-docs-pr/audio/ksproperty-audio-buffer-duration.md index af38560207..44438f5e0b 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-buffer-duration.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-buffer-duration.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_BUFFER\_DURATION property allows the size of keywords: ["KSPROPERTY_AUDIO_BUFFER_DURATION Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_BUFFER_DURATION api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_BUFFER\_DURATION diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-channel-config.md b/windows-driver-docs-pr/audio/ksproperty-audio-channel-config.md index 3367749cc9..4f04633969 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-channel-config.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-channel-config.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_CHANNEL\_CONFIG property specifies the actua keywords: ["KSPROPERTY_AUDIO_CHANNEL_CONFIG Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_CHANNEL_CONFIG api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_CHANNEL\_CONFIG diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-chorus-level.md b/windows-driver-docs-pr/audio/ksproperty-audio-chorus-level.md index 7766600f18..82cc4b79d5 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-chorus-level.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-chorus-level.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_CHORUS\_LEVEL property specifies the chorus keywords: ["KSPROPERTY_AUDIO_CHORUS_LEVEL Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_CHORUS_LEVEL api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_CHORUS\_LEVEL diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-chorus-modulation-depth.md b/windows-driver-docs-pr/audio/ksproperty-audio-chorus-modulation-depth.md index 5e67a42bd9..ae37b3b5f7 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-chorus-modulation-depth.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-chorus-modulation-depth.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_CHORUS\_MODULATION\_DEPTH property specifies keywords: ["KSPROPERTY_AUDIO_CHORUS_MODULATION_DEPTH Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_CHORUS_MODULATION_DEPTH api_location: - ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_CHORUS\_MODULATION\_DEPTH diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-chorus-modulation-rate.md b/windows-driver-docs-pr/audio/ksproperty-audio-chorus-modulation-rate.md index 7fd7e986a4..ed5d7f6584 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-chorus-modulation-rate.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-chorus-modulation-rate.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_CHORUS\_MODULATION\_RATE property specifies keywords: ["KSPROPERTY_AUDIO_CHORUS_MODULATION_RATE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_CHORUS_MODULATION_RATE api_location: - ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_CHORUS\_MODULATION\_RATE diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-copy-protection.md b/windows-driver-docs-pr/audio/ksproperty-audio-copy-protection.md index eefdff847d..2e2ff7e7cb 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-copy-protection.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-copy-protection.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_COPY\_PROTECTION property specifies the copy keywords: ["KSPROPERTY_AUDIO_COPY_PROTECTION Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_COPY_PROTECTION api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_COPY\_PROTECTION diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-cpu-resources.md b/windows-driver-docs-pr/audio/ksproperty-audio-cpu-resources.md index ae7c1f9994..bb251e2015 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-cpu-resources.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-cpu-resources.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_CPU\_RESOURCES property specifies whether a keywords: ["KSPROPERTY_AUDIO_CPU_RESOURCES Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_CPU_RESOURCES api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_CPU\_RESOURCES diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-delay.md b/windows-driver-docs-pr/audio/ksproperty-audio-delay.md index e98fe57c58..a0d270907b 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-delay.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-delay.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_DELAY property indicates the time lag that a keywords: ["KSPROPERTY_AUDIO_DELAY Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_DELAY api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_DELAY diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-demux-dest.md b/windows-driver-docs-pr/audio/ksproperty-audio-demux-dest.md index 21445e990d..570f4c2d60 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-demux-dest.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-demux-dest.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_DEMUX\_DEST property specifies the destinati keywords: ["KSPROPERTY_AUDIO_DEMUX_DEST Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_DEMUX_DEST api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_DEMUX\_DEST diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-dev-specific.md b/windows-driver-docs-pr/audio/ksproperty-audio-dev-specific.md index 4ba728a7a8..de5fdd8ded 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-dev-specific.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-dev-specific.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_DEV\_SPECIFIC property is used to access a d keywords: ["KSPROPERTY_AUDIO_DEV_SPECIFIC Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_DEV_SPECIFIC api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_DEV\_SPECIFIC diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-dynamic-range.md b/windows-driver-docs-pr/audio/ksproperty-audio-dynamic-range.md index 569fb2384f..2c51bf618e 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-dynamic-range.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-dynamic-range.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_DYNAMIC\_RANGE property specifies the dynami keywords: ["KSPROPERTY_AUDIO_DYNAMIC_RANGE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_DYNAMIC_RANGE api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_DYNAMIC\_RANGE diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-dynamic-sampling-rate.md b/windows-driver-docs-pr/audio/ksproperty-audio-dynamic-sampling-rate.md index 3f7aad90a9..cc43675d19 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-dynamic-sampling-rate.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-dynamic-sampling-rate.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_DYNAMIC\_SAMPLING\_RATE property is used to keywords: ["KSPROPERTY_AUDIO_DYNAMIC_SAMPLING_RATE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_DYNAMIC_SAMPLING_RATE api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_DYNAMIC\_SAMPLING\_RATE diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-eq-bands.md b/windows-driver-docs-pr/audio/ksproperty-audio-eq-bands.md index ceb000ef10..fa599251a0 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-eq-bands.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-eq-bands.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_EQ\_BANDS property specifies the set of freq keywords: ["KSPROPERTY_AUDIO_EQ_BANDS Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_EQ_BANDS api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_EQ\_BANDS diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-eq-level.md b/windows-driver-docs-pr/audio/ksproperty-audio-eq-level.md index 79bef31666..bcba2b88f1 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-eq-level.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-eq-level.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_EQ\_LEVEL property specifies the equalizatio keywords: ["KSPROPERTY_AUDIO_EQ_LEVEL Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_EQ_LEVEL api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_EQ\_LEVEL diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-filter-state.md b/windows-driver-docs-pr/audio/ksproperty-audio-filter-state.md index 7d4d752050..a9f73b97c9 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-filter-state.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-filter-state.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_FILTER\_STATE property is used to query a GF keywords: ["KSPROPERTY_AUDIO_FILTER_STATE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_FILTER_STATE api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_FILTER\_STATE diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-latency.md b/windows-driver-docs-pr/audio/ksproperty-audio-latency.md index 9ef3b25894..7545d3b74c 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-latency.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-latency.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_LATENCY property is used to report the delay keywords: ["KSPROPERTY_AUDIO_LATENCY Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_LATENCY api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_LATENCY diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-linear-buffer-position.md b/windows-driver-docs-pr/audio/ksproperty-audio-linear-buffer-position.md index f6f9febe32..bcfd74b419 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-linear-buffer-position.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-linear-buffer-position.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_LINEAR\_BUFFER\_POSITION property request re keywords: ["KSPROPERTY_AUDIO_LINEAR_BUFFER_POSITION Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_LINEAR_BUFFER_POSITION api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_LINEAR\_BUFFER\_POSITION diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-loudness.md b/windows-driver-docs-pr/audio/ksproperty-audio-loudness.md index 1a32d510db..0cd8d6132c 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-loudness.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-loudness.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_LOUDNESS property specifies whether loudness keywords: ["KSPROPERTY_AUDIO_LOUDNESS Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_LOUDNESS api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_LOUDNESS diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-manufacture-guid.md b/windows-driver-docs-pr/audio/ksproperty-audio-manufacture-guid.md index 412215b343..d5346f84b6 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-manufacture-guid.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-manufacture-guid.md @@ -4,13 +4,15 @@ description: Learn about the KSPROPERTY\_AUDIO\_MANUFACTURE\_GUID parameter. Thi keywords: ["KSPROPERTY_AUDIO_MANUFACTURE_GUID Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_MANUFACTURE_GUID api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_MANUFACTURE\_GUID diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-mic-array-geometry.md b/windows-driver-docs-pr/audio/ksproperty-audio-mic-array-geometry.md index 7f24a302ba..99d50235bd 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-mic-array-geometry.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-mic-array-geometry.md @@ -4,6 +4,7 @@ description: The KSPROPERTY\_AUDIO\_MIC\_ARRAY\_GEOMETRY property specifies the keywords: ["KSPROPERTY_AUDIO_MIC_ARRAY_GEOMETRY Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_MIC_ARRAY_GEOMETRY api_location: diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-mic-sensitivity.md b/windows-driver-docs-pr/audio/ksproperty-audio-mic-sensitivity.md index 10b9c9a07a..5b68bfd2ac 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-mic-sensitivity.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-mic-sensitivity.md @@ -4,6 +4,7 @@ description: The KSPROPERTY\_AUDIO\_MIC\_SENSITIVITY property specifies the micr keywords: ["KSPROPERTY_AUDIO_MIC_SENSITIVITY Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_MIC_SENSITIVITY api_location: diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-mic-sensitivity2.md b/windows-driver-docs-pr/audio/ksproperty-audio-mic-sensitivity2.md index 82c873f7ab..ccd2574006 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-mic-sensitivity2.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-mic-sensitivity2.md @@ -4,6 +4,7 @@ description: The KSPROPERTY_AUDIO_MIC_SENSITIVITY property specifies the microph keywords: ["KSPROPERTY_AUDIO_MIC_SENSITIVITY2 Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_MIC_SENSITIVITY2 api_location: diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-mic-snr.md b/windows-driver-docs-pr/audio/ksproperty-audio-mic-snr.md index 96d0bfbe9d..64b6258d69 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-mic-snr.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-mic-snr.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_MIC\_SNR property specifies the microphone s keywords: ["KSPROPERTY_AUDIO_MIC_SNR Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_MIC_SNR api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_MIC\_SNR diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-mid.md b/windows-driver-docs-pr/audio/ksproperty-audio-mid.md index 752478d4b0..7f0b3bc8f8 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-mid.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-mid.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_MID property specifies the mid-frequency lev keywords: ["KSPROPERTY_AUDIO_MID Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_MID api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_MID diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-mix-level-caps.md b/windows-driver-docs-pr/audio/ksproperty-audio-mix-level-caps.md index 00bb3065a8..18e157e65f 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-mix-level-caps.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-mix-level-caps.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_MIX\_LEVEL\_CAPS property specifies the mix- keywords: ["KSPROPERTY_AUDIO_MIX_LEVEL_CAPS Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_MIX_LEVEL_CAPS api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_MIX\_LEVEL\_CAPS diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-mix-level-table.md b/windows-driver-docs-pr/audio/ksproperty-audio-mix-level-table.md index 6533845c56..c9c520c10d 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-mix-level-table.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-mix-level-table.md @@ -4,6 +4,7 @@ description: The KSPROPERTY\_AUDIO\_MIX\_LEVEL\_TABLE property specifies the mix keywords: ["KSPROPERTY_AUDIO_MIX_LEVEL_TABLE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_MIX_LEVEL_TABLE api_location: diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-mute.md b/windows-driver-docs-pr/audio/ksproperty-audio-mute.md index 4d5385c2e1..2990d3e1a6 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-mute.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-mute.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_MUTE property specifies whether a channel on keywords: ["KSPROPERTY_AUDIO_MUTE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_MUTE api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_MUTE diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-mux-source.md b/windows-driver-docs-pr/audio/ksproperty-audio-mux-source.md index 4b2e56df27..97b56bd497 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-mux-source.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-mux-source.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_MUX\_SOURCE property specifies the source fo keywords: ["KSPROPERTY_AUDIO_MUX_SOURCE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_MUX_SOURCE api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_MUX\_SOURCE diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-num-eq-bands.md b/windows-driver-docs-pr/audio/ksproperty-audio-num-eq-bands.md index 1e4863da5d..fe6957a913 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-num-eq-bands.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-num-eq-bands.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_NUM\_EQ\_BANDS property is used to retrieve keywords: ["KSPROPERTY_AUDIO_NUM_EQ_BANDS Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_NUM_EQ_BANDS api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_NUM\_EQ\_BANDS diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-peakmeter.md b/windows-driver-docs-pr/audio/ksproperty-audio-peakmeter.md index 94c69751d3..67ebb2f54e 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-peakmeter.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-peakmeter.md @@ -4,6 +4,7 @@ description: The KSPROPERTY\_AUDIO\_PEAKMETER property retrieves the maximum aud keywords: ["KSPROPERTY_AUDIO_PEAKMETER Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_PEAKMETER api_location: diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-peakmeter2.md b/windows-driver-docs-pr/audio/ksproperty-audio-peakmeter2.md index 0bc5d45258..a9b88602b0 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-peakmeter2.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-peakmeter2.md @@ -4,6 +4,7 @@ description: Windows 8 introduces the KSPROPERTY\_AUDIO\_PEAKMETER2 property th keywords: ["KSPROPERTY_AUDIO_PEAKMETER2 Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_PEAKMETER2 api_location: diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-position.md b/windows-driver-docs-pr/audio/ksproperty-audio-position.md index dd70fac1ce..5cd7838e74 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-position.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-position.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_POSITION property specifies the current posi keywords: ["KSPROPERTY_AUDIO_POSITION Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_POSITION api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_POSITION diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-positionex.md b/windows-driver-docs-pr/audio/ksproperty-audio-positionex.md index 085057d67e..d0c00a4867 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-positionex.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-positionex.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_POSITIONEX property provides the caller with keywords: ["KSPROPERTY_AUDIO_POSITIONEX Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_POSITIONEX api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_POSITIONEX diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-preferred-status.md b/windows-driver-docs-pr/audio/ksproperty-audio-preferred-status.md index 054e9584f5..6f1e4b00cd 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-preferred-status.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-preferred-status.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_PREFERRED\_STATUS property informs a device keywords: ["KSPROPERTY_AUDIO_PREFERRED_STATUS Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_PREFERRED_STATUS api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_PREFERRED\_STATUS diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-presentation-position.md b/windows-driver-docs-pr/audio/ksproperty-audio-presentation-position.md index dbbef162d6..ad9b8a0e95 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-presentation-position.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-presentation-position.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_PRESENTATION\_POSITION property request retr keywords: ["KSPROPERTY_AUDIO_PRESENTATION_POSITION Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_PRESENTATION_POSITION api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_PRESENTATION\_POSITION diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-product-guid.md b/windows-driver-docs-pr/audio/ksproperty-audio-product-guid.md index 59861f5b2b..300010e9a1 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-product-guid.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-product-guid.md @@ -4,13 +4,15 @@ description: Learn about the KSPROPERTY\_AUDIO\_PRODUCT\_GUID parameter. This pa keywords: ["KSPROPERTY_AUDIO_PRODUCT_GUID Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_PRODUCT_GUID api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_PRODUCT\_GUID diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-quality.md b/windows-driver-docs-pr/audio/ksproperty-audio-quality.md index 2adb8aa4d1..39cae07ead 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-quality.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-quality.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_QUALITY property specifies the quality level keywords: ["KSPROPERTY_AUDIO_QUALITY Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_QUALITY api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_QUALITY diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-reverb-level.md b/windows-driver-docs-pr/audio/ksproperty-audio-reverb-level.md index f5d67cc2f0..7e054bfee8 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-reverb-level.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-reverb-level.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_REVERB\_LEVEL property specifies the current keywords: ["KSPROPERTY_AUDIO_REVERB_LEVEL Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_REVERB_LEVEL api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_REVERB\_LEVEL diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-reverb-time.md b/windows-driver-docs-pr/audio/ksproperty-audio-reverb-time.md index 6d2cd29c62..f0ec4d531c 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-reverb-time.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-reverb-time.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_REVERB\_TIME property specifies the reverber keywords: ["KSPROPERTY_AUDIO_REVERB_TIME Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_REVERB_TIME api_location: - ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_REVERB\_TIME diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-sampling-rate.md b/windows-driver-docs-pr/audio/ksproperty-audio-sampling-rate.md index 5ce118fd35..6096cca0c1 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-sampling-rate.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-sampling-rate.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_SAMPLING\_RATE property specifies the rate a keywords: ["KSPROPERTY_AUDIO_SAMPLING_RATE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_SAMPLING_RATE api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_SAMPLING\_RATE diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-stereo-enhance.md b/windows-driver-docs-pr/audio/ksproperty-audio-stereo-enhance.md index c0be088c64..cf4d2276c4 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-stereo-enhance.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-stereo-enhance.md @@ -4,13 +4,15 @@ description: Learn about the KSPROPERTY\_AUDIO\_STEREO\_ENHANCE parameter. This keywords: ["KSPROPERTY_AUDIO_STEREO_ENHANCE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_STEREO_ENHANCE api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_STEREO\_ENHANCE diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-stereo-speaker-geometry.md b/windows-driver-docs-pr/audio/ksproperty-audio-stereo-speaker-geometry.md index 1b0fc9f067..c18cd3efae 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-stereo-speaker-geometry.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-stereo-speaker-geometry.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_STEREO\_SPEAKER\_GEOMETRY property is used i keywords: ["KSPROPERTY_AUDIO_STEREO_SPEAKER_GEOMETRY Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_STEREO_SPEAKER_GEOMETRY api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_STEREO\_SPEAKER\_GEOMETRY diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-surround-encode.md b/windows-driver-docs-pr/audio/ksproperty-audio-surround-encode.md index 1a5eb7d0bf..5e8ad18cf6 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-surround-encode.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-surround-encode.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_SURROUND\_ENCODE property specifies whether keywords: ["KSPROPERTY_AUDIO_SURROUND_ENCODE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_SURROUND_ENCODE api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_SURROUND\_ENCODE diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-treble.md b/windows-driver-docs-pr/audio/ksproperty-audio-treble.md index ccab200a4f..8ed92a8940 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-treble.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-treble.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_TREBLE property specifies the treble level f keywords: ["KSPROPERTY_AUDIO_TREBLE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_TREBLE api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_TREBLE diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-volumelevel.md b/windows-driver-docs-pr/audio/ksproperty-audio-volumelevel.md index 1530633857..6843a75656 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-volumelevel.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-volumelevel.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_VOLUMELEVEL property specifies the volume le keywords: ["KSPROPERTY_AUDIO_VOLUMELEVEL Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_VOLUMELEVEL api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_VOLUMELEVEL diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-volumelimit-engaged.md b/windows-driver-docs-pr/audio/ksproperty-audio-volumelimit-engaged.md index d1940f3b7b..9384a6c33b 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-volumelimit-engaged.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-volumelimit-engaged.md @@ -4,15 +4,17 @@ description: KSPROPERTY\_AUDIO\_VOLUMELIMIT\_ENGAGED, is a new KS property that keywords: ["KSPROPERTY_AUDIO_VOLUMELIMIT_ENGAGED Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_VOLUMELIMIT_ENGAGED api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_VOLUMELIMIT\_ENGAGED diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-wavert-current-write-lastbuffer-position.md b/windows-driver-docs-pr/audio/ksproperty-audio-wavert-current-write-lastbuffer-position.md index 4ff5be3b92..9678cbe365 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-wavert-current-write-lastbuffer-position.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-wavert-current-write-lastbuffer-position.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_WAVERT\_CURRENT\_WRITE\_LASTBUFFER\_POSITION keywords: ["KSPROPERTY_AUDIO_WAVERT_CURRENT_WRITE_LASTBUFFER_POSITION Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_WAVERT_CURRENT_WRITE_LASTBUFFER_POSITION api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_WAVERT\_CURRENT\_WRITE\_LASTBUFFER\_POSITION diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-wavert-current-write-position.md b/windows-driver-docs-pr/audio/ksproperty-audio-wavert-current-write-position.md index 975e8918d9..4811977872 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-wavert-current-write-position.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-wavert-current-write-position.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_WAVERT\_CURRENT\_WRITE\_POSITION property re keywords: ["KSPROPERTY_AUDIO_WAVERT_CURRENT_WRITE_POSITION Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_WAVERT_CURRENT_WRITE_POSITION api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_WAVERT\_CURRENT\_WRITE\_POSITION diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-wide-mode.md b/windows-driver-docs-pr/audio/ksproperty-audio-wide-mode.md index 6164c596f5..23f02553a7 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-wide-mode.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-wide-mode.md @@ -4,13 +4,15 @@ description: This parameter name is reserved for future use. keywords: ["KSPROPERTY_AUDIO_WIDE_MODE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_WIDE_MODE api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_WIDE\_MODE diff --git a/windows-driver-docs-pr/audio/ksproperty-audio-wideness.md b/windows-driver-docs-pr/audio/ksproperty-audio-wideness.md index 574bf2efeb..9eab86997f 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audio-wideness.md +++ b/windows-driver-docs-pr/audio/ksproperty-audio-wideness.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIO\_WIDENESS property specifies the wideness (ap keywords: ["KSPROPERTY_AUDIO_WIDENESS Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIO_WIDENESS api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIO\_WIDENESS diff --git a/windows-driver-docs-pr/audio/ksproperty-audioeffectsdiscovery-effectslist.md b/windows-driver-docs-pr/audio/ksproperty-audioeffectsdiscovery-effectslist.md index f6fd8edb07..4bdb851461 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audioeffectsdiscovery-effectslist.md +++ b/windows-driver-docs-pr/audio/ksproperty-audioeffectsdiscovery-effectslist.md @@ -4,6 +4,7 @@ description: The KSPROPERTY\_AUDIOEFFECTSDISCOVERY\_EFFECTSLIST property specifi keywords: ["KSPROPERTY_AUDIOEFFECTSDISCOVERY_EFFECTSLIST Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIOEFFECTSDISCOVERY_EFFECTSLIST api_location: diff --git a/windows-driver-docs-pr/audio/ksproperty-audioengine-buffer-size-limits.md b/windows-driver-docs-pr/audio/ksproperty-audioengine-buffer-size-limits.md index e3d3b0d238..fe133dd0cf 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audioengine-buffer-size-limits.md +++ b/windows-driver-docs-pr/audio/ksproperty-audioengine-buffer-size-limits.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIOENGINE\_BUFFER\_SIZE\_RANGE property indicates keywords: ["KSPROPERTY_AUDIOENGINE_BUFFER_SIZE_RANGE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIOENGINE_BUFFER_SIZE_RANGE api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIOENGINE\_BUFFER\_SIZE\_RANGE diff --git a/windows-driver-docs-pr/audio/ksproperty-audioengine-descriptor.md b/windows-driver-docs-pr/audio/ksproperty-audioengine-descriptor.md index e55e2d9af2..05bb1f984e 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audioengine-descriptor.md +++ b/windows-driver-docs-pr/audio/ksproperty-audioengine-descriptor.md @@ -4,15 +4,17 @@ description: The audio driver for the offload-capable hardware solution uses KSP keywords: ["KSPROPERTY_AUDIOENGINE_DESCRIPTOR Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIOENGINE_DESCRIPTOR api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIOENGINE\_DESCRIPTOR diff --git a/windows-driver-docs-pr/audio/ksproperty-audioengine-deviceformat.md b/windows-driver-docs-pr/audio/ksproperty-audioengine-deviceformat.md index 26373c920f..3d738d6084 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audioengine-deviceformat.md +++ b/windows-driver-docs-pr/audio/ksproperty-audioengine-deviceformat.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIOENGINE\_DEVICEFORMAT property request retrieve keywords: ["KSPROPERTY_AUDIOENGINE_DEVICEFORMAT Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIOENGINE_DEVICEFORMAT api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIOENGINE\_DEVICEFORMAT diff --git a/windows-driver-docs-pr/audio/ksproperty-audioengine-gfx-enable.md b/windows-driver-docs-pr/audio/ksproperty-audioengine-gfx-enable.md index f254828af2..83045e8838 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audioengine-gfx-enable.md +++ b/windows-driver-docs-pr/audio/ksproperty-audioengine-gfx-enable.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIOENGINE\_GFXENABLE property request allows the keywords: ["KSPROPERTY_AUDIOENGINE_GFXENABLE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIOENGINE_GFXENABLE api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIOENGINE\_GFXENABLE diff --git a/windows-driver-docs-pr/audio/ksproperty-audioengine-lfx-enable.md b/windows-driver-docs-pr/audio/ksproperty-audioengine-lfx-enable.md index 26f58fba24..ad59b0f853 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audioengine-lfx-enable.md +++ b/windows-driver-docs-pr/audio/ksproperty-audioengine-lfx-enable.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIOENGINE\_LFXENABLE property request retrieves o keywords: ["KSPROPERTY_AUDIOENGINE_LFXENABLE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIOENGINE_LFXENABLE api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIOENGINE\_LFXENABLE diff --git a/windows-driver-docs-pr/audio/ksproperty-audioengine-loopback-protection.md b/windows-driver-docs-pr/audio/ksproperty-audioengine-loopback-protection.md index da126691e0..ec87e5e176 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audioengine-loopback-protection.md +++ b/windows-driver-docs-pr/audio/ksproperty-audioengine-loopback-protection.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIOENGINE\_LOOPBACK\_PROTECTION property request keywords: ["KSPROPERTY_AUDIOENGINE_LOOPBACK_PROTECTION Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIOENGINE_LOOPBACK_PROTECTION api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIOENGINE\_LOOPBACK\_PROTECTION diff --git a/windows-driver-docs-pr/audio/ksproperty-audioengine-mixformat.md b/windows-driver-docs-pr/audio/ksproperty-audioengine-mixformat.md index 812c9585de..45aa8fe61c 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audioengine-mixformat.md +++ b/windows-driver-docs-pr/audio/ksproperty-audioengine-mixformat.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIOENGINE\_MIXFORMAT property request retrieves t keywords: ["KSPROPERTY_AUDIOENGINE_MIXFORMAT Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIOENGINE_MIXFORMAT api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIOENGINE\_MIXFORMAT diff --git a/windows-driver-docs-pr/audio/ksproperty-audioengine-supporteddeviceformats.md b/windows-driver-docs-pr/audio/ksproperty-audioengine-supporteddeviceformats.md index 0a1bd85300..24d6ca93e0 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audioengine-supporteddeviceformats.md +++ b/windows-driver-docs-pr/audio/ksproperty-audioengine-supporteddeviceformats.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIOENGINE\_SUPPORTEDDEVICEFORMATS property reques keywords: ["KSPROPERTY_AUDIOENGINE_SUPPORTEDDEVICEFORMATS Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIOENGINE_SUPPORTEDDEVICEFORMATS api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIOENGINE\_SUPPORTEDDEVICEFORMATS diff --git a/windows-driver-docs-pr/audio/ksproperty-audioengine-volumelevel.md b/windows-driver-docs-pr/audio/ksproperty-audioengine-volumelevel.md index 3dece97168..32303fdd7c 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audioengine-volumelevel.md +++ b/windows-driver-docs-pr/audio/ksproperty-audioengine-volumelevel.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIOENGINE\_VOLUMELEVEL property specifies the vol keywords: ["KSPROPERTY_AUDIOENGINE_VOLUMELEVEL Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIOENGINE_VOLUMELEVEL api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIOENGINE\_VOLUMELEVEL diff --git a/windows-driver-docs-pr/audio/ksproperty-audioengine.md b/windows-driver-docs-pr/audio/ksproperty-audioengine.md index 15658db1e6..59da110260 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audioengine.md +++ b/windows-driver-docs-pr/audio/ksproperty-audioengine.md @@ -4,15 +4,17 @@ description: The properties contained in the KSPROPSETID\_AudioEngine property s keywords: ["KSPROPERTY_AUDIOENGINE enumeration Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIOENGINE api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIOENGINE enumeration @@ -20,7 +22,7 @@ The properties contained in the [KSPROPSETID\_AudioEngine](kspropsetid-audioengi ## Syntax -```ManagedCPlusPlus +```cpp typedef enum { KSPROPERTY_AUDIOENGINE_LFXENABLE               = 0, KSPROPERTY_AUDIOENGINE_GFXENABLE               = 1, diff --git a/windows-driver-docs-pr/audio/ksproperty-audiogfx-capturetargetdeviceid.md b/windows-driver-docs-pr/audio/ksproperty-audiogfx-capturetargetdeviceid.md index 6abae541cf..6403e9e064 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audiogfx-capturetargetdeviceid.md +++ b/windows-driver-docs-pr/audio/ksproperty-audiogfx-capturetargetdeviceid.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIOGFX\_CAPTURETARGETDEVICEID property is used to keywords: ["KSPROPERTY_AUDIOGFX_CAPTURETARGETDEVICEID Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIOGFX_CAPTURETARGETDEVICEID api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIOGFX\_CAPTURETARGETDEVICEID diff --git a/windows-driver-docs-pr/audio/ksproperty-audiogfx-rendertargetdeviceid.md b/windows-driver-docs-pr/audio/ksproperty-audiogfx-rendertargetdeviceid.md index 7c130acbda..2faf470c94 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audiogfx-rendertargetdeviceid.md +++ b/windows-driver-docs-pr/audio/ksproperty-audiogfx-rendertargetdeviceid.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIOGFX\_RENDERTARGETDEVICEID property is used to keywords: ["KSPROPERTY_AUDIOGFX_RENDERTARGETDEVICEID Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIOGFX_RENDERTARGETDEVICEID api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIOGFX\_RENDERTARGETDEVICEID diff --git a/windows-driver-docs-pr/audio/ksproperty-audiomodule-command.md b/windows-driver-docs-pr/audio/ksproperty-audiomodule-command.md index 0e0d11d541..1744bcb40e 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audiomodule-command.md +++ b/windows-driver-docs-pr/audio/ksproperty-audiomodule-command.md @@ -4,13 +4,15 @@ description: The KSPROPERTY\_AUDIOMODULE\_COMMAND property is a command property keywords: ["KSPROPERTY_AUDIOMODULE_COMMAND Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIOMODULE_COMMAND api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIOMODULE\_COMMAND diff --git a/windows-driver-docs-pr/audio/ksproperty-audiomodule-descriptors.md b/windows-driver-docs-pr/audio/ksproperty-audiomodule-descriptors.md index 8b54fc5817..2829b3f1e0 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audiomodule-descriptors.md +++ b/windows-driver-docs-pr/audio/ksproperty-audiomodule-descriptors.md @@ -4,13 +4,15 @@ description: KSPROPERTY\_AUDIOMODULE\_DESCRIPTORS is used to retrieves the stati keywords: ["KSPROPERTY_AUDIOMODULE_DESCRIPTORS Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIOMODULE_DESCRIPTORS api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIOMODULE\_DESCRIPTORS diff --git a/windows-driver-docs-pr/audio/ksproperty-audiomodule-notification-device-id.md b/windows-driver-docs-pr/audio/ksproperty-audiomodule-notification-device-id.md index b70a873ca5..13eba8314a 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audiomodule-notification-device-id.md +++ b/windows-driver-docs-pr/audio/ksproperty-audiomodule-notification-device-id.md @@ -4,13 +4,15 @@ description: The KSPROPERTY\_AUDIOMODULE\_NOTIFICATION\_DEVICE\_ID retrieves the keywords: ["KSPROPERTY_AUDIOMODULE_NOTIFICATION_DEVICE_ID Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIOMODULE_NOTIFICATION_DEVICE_ID api_type: - NA -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIOMODULE\_NOTIFICATION\_DEVICE\_ID diff --git a/windows-driver-docs-pr/audio/ksproperty-audiomodule.md b/windows-driver-docs-pr/audio/ksproperty-audiomodule.md index d14a94c681..29ce65c40d 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audiomodule.md +++ b/windows-driver-docs-pr/audio/ksproperty-audiomodule.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIOMODULE enumeration defines constants that are keywords: ["KSPROPERTY_AUDIOMODULE enumeration Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIOMODULE api_location: - ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIOMODULE enumeration @@ -22,7 +24,7 @@ For more information about audio modules, see [Implementing Audio Module Discove ## Syntax -```ManagedCPlusPlus +```cpp typedef enum { KSPROPERTY_AUDIOMODULE_DESCRIPTORS            = 1, KSPROPERTY_AUDIOMODULE_COMMAND                 = 2, diff --git a/windows-driver-docs-pr/audio/ksproperty-audiosignalprocessing-modes.md b/windows-driver-docs-pr/audio/ksproperty-audiosignalprocessing-modes.md index da80c7965b..887cc7dc63 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audiosignalprocessing-modes.md +++ b/windows-driver-docs-pr/audio/ksproperty-audiosignalprocessing-modes.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIOSIGNALPROCESSING\_MODES property returns the l keywords: ["KSPROPERTY_AUDIOSIGNALPROCESSING_MODES Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIOSIGNALPROCESSING_MODES api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIOSIGNALPROCESSING\_MODES diff --git a/windows-driver-docs-pr/audio/ksproperty-audiosignalprocessing.md b/windows-driver-docs-pr/audio/ksproperty-audiosignalprocessing.md index 83321396e6..4d0128eaee 100644 --- a/windows-driver-docs-pr/audio/ksproperty-audiosignalprocessing.md +++ b/windows-driver-docs-pr/audio/ksproperty-audiosignalprocessing.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_AUDIOSIGNALPROCESSING enumeration defines a constan keywords: ["KSPROPERTY_AUDIOSIGNALPROCESSING enumeration Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_AUDIOSIGNALPROCESSING api_location: - ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_AUDIOSIGNALPROCESSING enumeration @@ -20,7 +22,7 @@ The KSPROPERTY\_AUDIOSIGNALPROCESSING enumeration defines a constant that is use ## Syntax -```ManagedCPlusPlus +```cpp typedef enum _KSPROPERTY_AUDIOSIGNALPROCESSING { KSPROPERTY_AUDIOSIGNALPROCESSING_MODES } KSPROPERTY_AUDIOSIGNALPROCESSING; diff --git a/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-all.md b/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-all.md index ac50bde683..eeca09851c 100644 --- a/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-all.md +++ b/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-all.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_DIRECTSOUND3DBUFFER\_ALL property is used to get or keywords: ["KSPROPERTY_DIRECTSOUND3DBUFFER_ALL Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_DIRECTSOUND3DBUFFER_ALL api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_DIRECTSOUND3DBUFFER\_ALL diff --git a/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-coneangles.md b/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-coneangles.md index 5fd9125c99..805b20d5da 100644 --- a/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-coneangles.md +++ b/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-coneangles.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_DIRECTSOUND3DBUFFER\_CONEANGLES property specifies keywords: ["KSPROPERTY_DIRECTSOUND3DBUFFER_CONEANGLES Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_DIRECTSOUND3DBUFFER_CONEANGLES api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_DIRECTSOUND3DBUFFER\_CONEANGLES diff --git a/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-coneorientation.md b/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-coneorientation.md index 0321d63d12..c00dd7384a 100644 --- a/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-coneorientation.md +++ b/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-coneorientation.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_DIRECTSOUND3DBUFFER\_CONEORIENTATION property speci keywords: ["KSPROPERTY_DIRECTSOUND3DBUFFER_CONEORIENTATION Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_DIRECTSOUND3DBUFFER_CONEORIENTATION api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_DIRECTSOUND3DBUFFER\_CONEORIENTATION diff --git a/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-coneoutsidevolume.md b/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-coneoutsidevolume.md index b0cd2ac5ce..2396233d1a 100644 --- a/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-coneoutsidevolume.md +++ b/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-coneoutsidevolume.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_DIRECTSOUND3DBUFFER\_CONEOUTSIDEVOLUME property spe keywords: ["KSPROPERTY_DIRECTSOUND3DBUFFER_CONEOUTSIDEVOLUME Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_DIRECTSOUND3DBUFFER_CONEOUTSIDEVOLUME api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_DIRECTSOUND3DBUFFER\_CONEOUTSIDEVOLUME diff --git a/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-maxdistance.md b/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-maxdistance.md index 4049366abe..a1ee2228d0 100644 --- a/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-maxdistance.md +++ b/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-maxdistance.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_DIRECTSOUND3DBUFFER\_MAXDISTANCE property specifies keywords: ["KSPROPERTY_DIRECTSOUND3DBUFFER_MAXDISTANCE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_DIRECTSOUND3DBUFFER_MAXDISTANCE api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_DIRECTSOUND3DBUFFER\_MAXDISTANCE diff --git a/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-mindistance.md b/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-mindistance.md index d20131bb36..3dcf668132 100644 --- a/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-mindistance.md +++ b/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-mindistance.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_DIRECTSOUND3DBUFFER\_MINDISTANCE property specifies keywords: ["KSPROPERTY_DIRECTSOUND3DBUFFER_MINDISTANCE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_DIRECTSOUND3DBUFFER_MINDISTANCE api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_DIRECTSOUND3DBUFFER\_MINDISTANCE diff --git a/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-mode.md b/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-mode.md index c3a6bb11c7..5980845a09 100644 --- a/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-mode.md +++ b/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-mode.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_DIRECTSOUND3DBUFFER\_MODE property specifies the pr keywords: ["KSPROPERTY_DIRECTSOUND3DBUFFER_MODE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_DIRECTSOUND3DBUFFER_MODE api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_DIRECTSOUND3DBUFFER\_MODE diff --git a/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-position.md b/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-position.md index 69edcf6911..58977c6195 100644 --- a/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-position.md +++ b/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-position.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_DIRECTSOUND3DBUFFER\_POSITION property specifies th keywords: ["KSPROPERTY_DIRECTSOUND3DBUFFER_POSITION Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_DIRECTSOUND3DBUFFER_POSITION api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_DIRECTSOUND3DBUFFER\_POSITION diff --git a/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-velocity.md b/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-velocity.md index 5d0dfc864d..0772f08982 100644 --- a/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-velocity.md +++ b/windows-driver-docs-pr/audio/ksproperty-directsound3dbuffer-velocity.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_DIRECTSOUND3DBUFFER\_VELOCITY property specifies th keywords: ["KSPROPERTY_DIRECTSOUND3DBUFFER_VELOCITY Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_DIRECTSOUND3DBUFFER_VELOCITY api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_DIRECTSOUND3DBUFFER\_VELOCITY diff --git a/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-all.md b/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-all.md index e274dc0e65..e3d3f0d770 100644 --- a/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-all.md +++ b/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-all.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_DIRECTSOUND3DLISTENER\_ALL property is used to set keywords: ["KSPROPERTY_DIRECTSOUND3DLISTENER_ALL Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_DIRECTSOUND3DLISTENER_ALL api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_DIRECTSOUND3DLISTENER\_ALL diff --git a/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-allocation.md b/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-allocation.md index caa9a6b9b7..1f19604ebb 100644 --- a/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-allocation.md +++ b/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-allocation.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_DIRECTSOUND3DLISTENER\_ALLOCATION property is used keywords: ["KSPROPERTY_DIRECTSOUND3DLISTENER_ALLOCATION Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_DIRECTSOUND3DLISTENER_ALLOCATION api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_DIRECTSOUND3DLISTENER\_ALLOCATION diff --git a/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-batch.md b/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-batch.md index 13abdf6e32..b821950d17 100644 --- a/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-batch.md +++ b/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-batch.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_DIRECTSOUND3DLISTENER\_BATCH property specifies the keywords: ["KSPROPERTY_DIRECTSOUND3DLISTENER_BATCH Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_DIRECTSOUND3DLISTENER_BATCH api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_DIRECTSOUND3DLISTENER\_BATCH diff --git a/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-distancefactor.md b/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-distancefactor.md index cafa723f83..e42fbb3962 100644 --- a/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-distancefactor.md +++ b/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-distancefactor.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_DIRECTSOUND3DLISTENER\_DISTANCEFACTOR property spec keywords: ["KSPROPERTY_DIRECTSOUND3DLISTENER_DISTANCEFACTOR Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_DIRECTSOUND3DLISTENER_DISTANCEFACTOR api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_DIRECTSOUND3DLISTENER\_DISTANCEFACTOR diff --git a/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-dopplerfactor.md b/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-dopplerfactor.md index 6868497ca2..af5ae3360a 100644 --- a/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-dopplerfactor.md +++ b/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-dopplerfactor.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_DIRECTSOUND3DLISTENER\_DOPPLERFACTOR property speci keywords: ["KSPROPERTY_DIRECTSOUND3DLISTENER_DOPPLERFACTOR Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_DIRECTSOUND3DLISTENER_DOPPLERFACTOR api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_DIRECTSOUND3DLISTENER\_DOPPLERFACTOR diff --git a/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-orientation.md b/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-orientation.md index 03c6b0ab7f..cc2cea5afa 100644 --- a/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-orientation.md +++ b/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-orientation.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_DIRECTSOUND3DLISTENER\_ORIENTATION property specifi keywords: ["KSPROPERTY_DIRECTSOUND3DLISTENER_ORIENTATION Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_DIRECTSOUND3DLISTENER_ORIENTATION api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_DIRECTSOUND3DLISTENER\_ORIENTATION diff --git a/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-position.md b/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-position.md index 3c47b75bfc..6693ccfb8b 100644 --- a/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-position.md +++ b/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-position.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_DIRECTSOUND3DLISTENER\_POSITION property specifies keywords: ["KSPROPERTY_DIRECTSOUND3DLISTENER_POSITION Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_DIRECTSOUND3DLISTENER_POSITION api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_DIRECTSOUND3DLISTENER\_POSITION diff --git a/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-rollofffactor.md b/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-rollofffactor.md index f6ffeb3084..a8bfacb790 100644 --- a/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-rollofffactor.md +++ b/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-rollofffactor.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_DIRECTSOUND3DLISTENER\_ROLLOFFFACTOR property speci keywords: ["KSPROPERTY_DIRECTSOUND3DLISTENER_ROLLOFFFACTOR Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_DIRECTSOUND3DLISTENER_ROLLOFFFACTOR api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_DIRECTSOUND3DLISTENER\_ROLLOFFFACTOR diff --git a/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-velocity.md b/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-velocity.md index 6840550c8f..c5737e7b5a 100644 --- a/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-velocity.md +++ b/windows-driver-docs-pr/audio/ksproperty-directsound3dlistener-velocity.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_DIRECTSOUND3DLISTENER\_VELOCITY property specifies keywords: ["KSPROPERTY_DIRECTSOUND3DLISTENER_VELOCITY Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_DIRECTSOUND3DLISTENER_VELOCITY api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_DIRECTSOUND3DLISTENER\_VELOCITY diff --git a/windows-driver-docs-pr/audio/ksproperty-fmrx-antennaendpointid.md b/windows-driver-docs-pr/audio/ksproperty-fmrx-antennaendpointid.md index 4ae5c3f5c7..a375886e5d 100644 --- a/windows-driver-docs-pr/audio/ksproperty-fmrx-antennaendpointid.md +++ b/windows-driver-docs-pr/audio/ksproperty-fmrx-antennaendpointid.md @@ -4,15 +4,17 @@ description: The KSTOPOLOGY\_ENDPOINTID property contains information about the keywords: ["KSPROPERTY_FMRX_ANTENNAENDPOINTID Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_FMRX_ANTENNAENDPOINTID api_location: - ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_FMRX\_ANTENNAENDPOINTID diff --git a/windows-driver-docs-pr/audio/ksproperty-fmrx-endpointid.md b/windows-driver-docs-pr/audio/ksproperty-fmrx-endpointid.md index ba69c37305..ee2425618a 100644 --- a/windows-driver-docs-pr/audio/ksproperty-fmrx-endpointid.md +++ b/windows-driver-docs-pr/audio/ksproperty-fmrx-endpointid.md @@ -4,15 +4,17 @@ description: The KSTOPOLOGY\_ENDPOINTID property contains the endpoint ID for th keywords: ["KSPROPERTY_FMRX_ENDPOINTID Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_FMRX_ENDPOINTID api_location: - ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_FMRX\_ENDPOINTID diff --git a/windows-driver-docs-pr/audio/ksproperty-fmrx-state.md b/windows-driver-docs-pr/audio/ksproperty-fmrx-state.md index 72ca048132..e3b0a57741 100644 --- a/windows-driver-docs-pr/audio/ksproperty-fmrx-state.md +++ b/windows-driver-docs-pr/audio/ksproperty-fmrx-state.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_FMRX\_STATE property specifies whether FM radio is keywords: ["KSPROPERTY_FMRX_STATE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_FMRX_STATE api_location: - ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_FMRX\_STATE diff --git a/windows-driver-docs-pr/audio/ksproperty-fmrx-volume.md b/windows-driver-docs-pr/audio/ksproperty-fmrx-volume.md index 6369da39f0..31b11afa32 100644 --- a/windows-driver-docs-pr/audio/ksproperty-fmrx-volume.md +++ b/windows-driver-docs-pr/audio/ksproperty-fmrx-volume.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_FMRX\_VOLUME property controls the volume of the FM keywords: ["KSPROPERTY_FMRX_VOLUME Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_FMRX_VOLUME api_location: - ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_FMRX\_VOLUME diff --git a/windows-driver-docs-pr/audio/ksproperty-hrtf3d-filter-format.md b/windows-driver-docs-pr/audio/ksproperty-hrtf3d-filter-format.md index 3fdc84c637..ad6d5bb7b6 100644 --- a/windows-driver-docs-pr/audio/ksproperty-hrtf3d-filter-format.md +++ b/windows-driver-docs-pr/audio/ksproperty-hrtf3d-filter-format.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_HRTF3D\_FILTER\_FORMAT property retrieves the filte keywords: ["KSPROPERTY_HRTF3D_FILTER_FORMAT Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_HRTF3D_FILTER_FORMAT api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_HRTF3D\_FILTER\_FORMAT diff --git a/windows-driver-docs-pr/audio/ksproperty-hrtf3d-initialize.md b/windows-driver-docs-pr/audio/ksproperty-hrtf3d-initialize.md index 41857646df..14e92e2690 100644 --- a/windows-driver-docs-pr/audio/ksproperty-hrtf3d-initialize.md +++ b/windows-driver-docs-pr/audio/ksproperty-hrtf3d-initialize.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_HRTF3D\_INITIALIZE property specifies the parameter keywords: ["KSPROPERTY_HRTF3D_INITIALIZE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_HRTF3D_INITIALIZE api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_HRTF3D\_INITIALIZE diff --git a/windows-driver-docs-pr/audio/ksproperty-hrtf3d-params.md b/windows-driver-docs-pr/audio/ksproperty-hrtf3d-params.md index 7298f2929d..baeedad932 100644 --- a/windows-driver-docs-pr/audio/ksproperty-hrtf3d-params.md +++ b/windows-driver-docs-pr/audio/ksproperty-hrtf3d-params.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_HRTF3D\_PARAMS property applies a set of 3-D parame keywords: ["KSPROPERTY_HRTF3D_PARAMS Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_HRTF3D_PARAMS api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_HRTF3D\_PARAMS diff --git a/windows-driver-docs-pr/audio/ksproperty-interleavedaudio-formatinformation.md b/windows-driver-docs-pr/audio/ksproperty-interleavedaudio-formatinformation.md index 119bef5d6b..1cc0b17e6d 100644 --- a/windows-driver-docs-pr/audio/ksproperty-interleavedaudio-formatinformation.md +++ b/windows-driver-docs-pr/audio/ksproperty-interleavedaudio-formatinformation.md @@ -4,6 +4,7 @@ description: The KSPROPERTY\_INTERLEAVEDAUDIO_FORMATINFORMATION property provide keywords: ["KSPROPERTY_INTERLEAVEDAUDIO_FORMATINFORMATION Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_INTERLEAVEDAUDIO_FORMATINFORMATION api_location: diff --git a/windows-driver-docs-pr/audio/ksproperty-itd3d-params.md b/windows-driver-docs-pr/audio/ksproperty-itd3d-params.md index 5db4d5f8c0..6dfc356d30 100644 --- a/windows-driver-docs-pr/audio/ksproperty-itd3d-params.md +++ b/windows-driver-docs-pr/audio/ksproperty-itd3d-params.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_ITD3D\_PARAMS property is used to set the parameter keywords: ["KSPROPERTY_ITD3D_PARAMS Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_ITD3D_PARAMS api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_ITD3D\_PARAMS diff --git a/windows-driver-docs-pr/audio/ksproperty-jack-containerid.md b/windows-driver-docs-pr/audio/ksproperty-jack-containerid.md index fe98be7b45..7d393132c8 100644 --- a/windows-driver-docs-pr/audio/ksproperty-jack-containerid.md +++ b/windows-driver-docs-pr/audio/ksproperty-jack-containerid.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_JACK\_CONTAINERID property is implemented as a pin- keywords: ["KSPROPERTY_JACK_CONTAINERID Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_JACK_CONTAINERID api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_JACK\_CONTAINERID diff --git a/windows-driver-docs-pr/audio/ksproperty-jack-description.md b/windows-driver-docs-pr/audio/ksproperty-jack-description.md index 913a0d9365..0b202fa7dc 100644 --- a/windows-driver-docs-pr/audio/ksproperty-jack-description.md +++ b/windows-driver-docs-pr/audio/ksproperty-jack-description.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_JACK\_DESCRIPTION property is implemented as a mult keywords: ["KSPROPERTY_JACK_DESCRIPTION Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_JACK_DESCRIPTION api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_JACK\_DESCRIPTION diff --git a/windows-driver-docs-pr/audio/ksproperty-jack-description2.md b/windows-driver-docs-pr/audio/ksproperty-jack-description2.md index ea9b30a5b5..220811f6ad 100644 --- a/windows-driver-docs-pr/audio/ksproperty-jack-description2.md +++ b/windows-driver-docs-pr/audio/ksproperty-jack-description2.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_JACK\_DESCRIPTION2 property is implemented as a pin keywords: ["KSPROPERTY_JACK_DESCRIPTION2 Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_JACK_DESCRIPTION2 api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_JACK\_DESCRIPTION2 diff --git a/windows-driver-docs-pr/audio/ksproperty-jack-description3.md b/windows-driver-docs-pr/audio/ksproperty-jack-description3.md new file mode 100644 index 0000000000..186bbed3c1 --- /dev/null +++ b/windows-driver-docs-pr/audio/ksproperty-jack-description3.md @@ -0,0 +1,115 @@ +--- +title: KSPROPERTY\_JACK\_DESCRIPTION3 +description: The KSPROPERTY\_JACK\_DESCRIPTION3 property is implemented as a pin-wise property that is accessed by using the filter handle. +keywords: ["KSPROPERTY_JACK_DESCRIPTION3 Audio Devices"] +topic_type: +- apiref +ms.topic: reference +api_name: +- KSPROPERTY_JACK_DESCRIPTION3 +api_location: +- Ksmedia.h +api_type: +- HeaderDef +ms.date: 10/26/2022 +--- + +# KSPROPERTY\_JACK\_DESCRIPTION3 + +The **KSPROPERTY\_JACK\_DESCRIPTION3** property is implemented as a pin-wise property that is accessed by using the filter handle. + +In version 22H2 and later Windows operating systems, the associated [**KSJACK\_DESCRIPTION3**](ksjack-description3.md) structure can be used to specify and change the current configuration of the jack. + +### Usage Summary Table + + +++++++ + + + + + + + + + + + + + + + + + + +
GetSetTargetProperty descriptor typeProperty value type

Yes

No

Pin factory (via filter handle)

KSP_PIN

KSMULTIPLE_ITEM followed by an array of KSJACK_DESCRIPTION3 structures

+ +The property value (instance data) is a KSMULTIPLE\_ITEM, followed by an array of KSJACK\_DESCRIPTION3 structures. + +### Return Value + +A KSPROPERTY\_JACK\_DESCRIPTION3 property request returns a KSMULTIPLE\_ITEM followed by an array of *N* KSJACK\_DESCRIPTION3 structures, where *N* = the number of jacks that are associated with the specified bridge pin. The following list shows the items that are returned by the property request. + +KSMULTIPLE\_ITEM.Size = sizeof(KSMULTIPLE\_ITEM) + N \* sizeof(KSJACK\_DESCRIPTION3) + +KSMULTIPLE\_ITEM.Count = N + +KSJACK\_DESCRIPTION3\[0\] + +... + +KSJACK\_DESCRIPTION3\[N-1\] + +## Remarks + +### Communicating audio device changes using KSJACK_DESCRIPTION3 and KSPROPERTY_JACK_DESCRIPTION3 + +The Windows audio system caches audio device capabilities during audio endpoint creation. These cached values are for capabilities such as the presence of a HW audio engine, format support, container ID, buffer size characteristics, etc. These cached values are retained for the life of the windows installation. They are refreshed only when the audio driver is updated or during an OS upgrade. + +With [**KSJACK_DESCRIPTION3**](ksjack-description3.md), the Windows audio system provides a mechanism for the audio driver to request all cached values be discarded and refreshed. The request can be triggered by changes in the audio device capabilities such as resource constraints. + +Whenever the driver changes the contents of KSJACK\_DESCRIPTION3 at runtime, the driver will trigger the existing [KSEVENT_PINCAPS_JACKINFOCHANGE](ksproperty-jack-description3.md) event. + +The Windows audio system maintains the last reported *ConfigId* value cached on the audio endpoint. The *ConfigId* value is retrieved in response to [KSEVENT_PINCAPS_JACKINFOCHANGE](ksproperty-jack-description3.md) event and during normal processing of the audio endpoint at system boot, Audio Endpoint Builder service restart, audio driver update, or interface state changes for the endpoint. + +If the retrieved *ConfigId* value differs from the previously stored value, the Windows audio system will discard all previously cached endpoint capabilities and refresh them. + +The recommended usage is to define multiple audio endpoint configurations within the driver that is controlled by the *ConfigId* (bitmask or enum) value. For example, *ConfigId* of 1 may indicate the presence of an audio engine node, whereas *ConfigId* 2 would not report an audio engine node. The *ConfigId* in use by the driver is shared with the Windows audio system through KSPROPERTY_JACK_DESCRIPTION3 and acts to synchronize the endpoint with the capabilities cached by the Windows audio system. + +The value of the *ConfigId* is opaque to Windows. The audio driver could use a timestamp or incrementing value chosen at run time in place of a bitmask or enum as suggested above. This strategy is not recommended as it may result in unnecessary endpoint refreshes during boot up or interface changes to synchronize the last stored *ConfigId* value to the newly reported value, even when the endpoint capabilities are unchanged. This approach may also increase the chances of the driver and Windows becoming out of sync, which can result in audio playback failures. + +The mechanism used to refresh the cached values on the endpoint when the *ConfigId* changes is the same as used for Operating System Upgrades and Driver Updates. A new endpoint with a different ID is created which will contain the refreshed cached values that match the new *ConfigId* settings for the endpoint, user settings are then copied from the old endpoint to the new endpoint, and finally the old endpoint is deleted. For more information, on the audio endpoint migration process in OS upgrades, see [Operating System Upgrades](operating-system-upgrades.md). + +## Requirements + + ++++ + + + + + + + + + + +

Minimum supported client

Available in version 22H2 and later Windows operating systems.

Header

Ksmedia.h
+ +## See also + + +[**KSJACK\_DESCRIPTION3**](ksjack-description3.md) + +[KSMULTIPLE\_ITEM](/windows-hardware/drivers/ddi/ks/ns-ks-ksmultiple_item) + +[Operating System Upgrades](operating-system-upgrades.md) diff --git a/windows-driver-docs-pr/audio/ksproperty-jack-sink-info.md b/windows-driver-docs-pr/audio/ksproperty-jack-sink-info.md index ea1917353f..106123a585 100644 --- a/windows-driver-docs-pr/audio/ksproperty-jack-sink-info.md +++ b/windows-driver-docs-pr/audio/ksproperty-jack-sink-info.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_JACK\_SINK\_INFO property is implemented as a pin-w keywords: ["KSPROPERTY_JACK_SINK_INFO Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_JACK_SINK_INFO api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_JACK\_SINK\_INFO diff --git a/windows-driver-docs-pr/audio/ksproperty-jack.md b/windows-driver-docs-pr/audio/ksproperty-jack.md index 1ff25609a7..e47781434b 100644 --- a/windows-driver-docs-pr/audio/ksproperty-jack.md +++ b/windows-driver-docs-pr/audio/ksproperty-jack.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_JACK enumeration defines new property IDs that are keywords: ["KSPROPERTY_JACK enumeration Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_JACK api_location: - ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_JACK enumeration @@ -20,7 +22,7 @@ The `KSPROPERTY_JACK` enumeration defines new property IDs that are used by audi ## Syntax -```ManagedCPlusPlus +```cpp typedef enum { KSPROPERTY_JACK_DESCRIPTION   = 1, KSPROPERTY_JACK_DESCRIPTION2  = 2, diff --git a/windows-driver-docs-pr/audio/ksproperty-oneshot-disconnect.md b/windows-driver-docs-pr/audio/ksproperty-oneshot-disconnect.md index 4665e3d65e..d165d7b867 100644 --- a/windows-driver-docs-pr/audio/ksproperty-oneshot-disconnect.md +++ b/windows-driver-docs-pr/audio/ksproperty-oneshot-disconnect.md @@ -4,17 +4,18 @@ description: The KSPROPERTY\_ONESHOT\_DISCONNECT property is used to prompt the keywords: ["KSPROPERTY_ONESHOT_DISCONNECT Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_ONESHOT_DISCONNECT api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- -# KSPROPERTY\_ONESHOT\_DISCONNECT +# KSPROPERTY\_ONESHOT\_DISCONNECT The **KSPROPERTY\_ONESHOT\_DISCONNECT** property is used to prompt the audio driver to disconnect from the Bluetooth audio device. diff --git a/windows-driver-docs-pr/audio/ksproperty-oneshot-reconnect.md b/windows-driver-docs-pr/audio/ksproperty-oneshot-reconnect.md index 0cfc0ae8e5..29d23ac97b 100644 --- a/windows-driver-docs-pr/audio/ksproperty-oneshot-reconnect.md +++ b/windows-driver-docs-pr/audio/ksproperty-oneshot-reconnect.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_ONESHOT\_RECONNECT property is used to prompt the a keywords: ["KSPROPERTY_ONESHOT_RECONNECT Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_ONESHOT_RECONNECT api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_ONESHOT\_RECONNECT diff --git a/windows-driver-docs-pr/audio/ksproperty-rtaudio-buffer-with-notification.md b/windows-driver-docs-pr/audio/ksproperty-rtaudio-buffer-with-notification.md index ef161accfb..b4c08a0821 100644 --- a/windows-driver-docs-pr/audio/ksproperty-rtaudio-buffer-with-notification.md +++ b/windows-driver-docs-pr/audio/ksproperty-rtaudio-buffer-with-notification.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_RTAUDIO\_BUFFER\_WITH\_NOTIFICATION property specif keywords: ["KSPROPERTY_RTAUDIO_BUFFER_WITH_NOTIFICATION Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_RTAUDIO_BUFFER_WITH_NOTIFICATION api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_RTAUDIO\_BUFFER\_WITH\_NOTIFICATION diff --git a/windows-driver-docs-pr/audio/ksproperty-rtaudio-buffer.md b/windows-driver-docs-pr/audio/ksproperty-rtaudio-buffer.md index 2184f8263e..86985da13a 100644 --- a/windows-driver-docs-pr/audio/ksproperty-rtaudio-buffer.md +++ b/windows-driver-docs-pr/audio/ksproperty-rtaudio-buffer.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_RTAUDIO\_BUFFER property specifies a driver-allocat keywords: ["KSPROPERTY_RTAUDIO_BUFFER Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_RTAUDIO_BUFFER api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_RTAUDIO\_BUFFER diff --git a/windows-driver-docs-pr/audio/ksproperty-rtaudio-clockregister.md b/windows-driver-docs-pr/audio/ksproperty-rtaudio-clockregister.md index f3bd7e5f41..fb606b9e54 100644 --- a/windows-driver-docs-pr/audio/ksproperty-rtaudio-clockregister.md +++ b/windows-driver-docs-pr/audio/ksproperty-rtaudio-clockregister.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_RTAUDIO\_CLOCKREGISTER property maps the wall clock keywords: ["KSPROPERTY_RTAUDIO_CLOCKREGISTER Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_RTAUDIO_CLOCKREGISTER api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_RTAUDIO\_CLOCKREGISTER diff --git a/windows-driver-docs-pr/audio/ksproperty-rtaudio-getreadpacket.md b/windows-driver-docs-pr/audio/ksproperty-rtaudio-getreadpacket.md index 9da73bc837..f23323ea89 100644 --- a/windows-driver-docs-pr/audio/ksproperty-rtaudio-getreadpacket.md +++ b/windows-driver-docs-pr/audio/ksproperty-rtaudio-getreadpacket.md @@ -4,6 +4,7 @@ description: KSPROPERTY\_RTAUDIO\_GETREADPACKET returns information about captur keywords: ["KSPROPERTY_RTAUDIO_GETREADPACKET Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_RTAUDIO_GETREADPACKET api_location: diff --git a/windows-driver-docs-pr/audio/ksproperty-rtaudio-hwlatency.md b/windows-driver-docs-pr/audio/ksproperty-rtaudio-hwlatency.md index d6a08f3b37..fdb64ddd2d 100644 --- a/windows-driver-docs-pr/audio/ksproperty-rtaudio-hwlatency.md +++ b/windows-driver-docs-pr/audio/ksproperty-rtaudio-hwlatency.md @@ -4,6 +4,7 @@ description: The KSPROPERTY\_RTAUDIO\_HWLATENCY property retrieves a description keywords: ["KSPROPERTY_RTAUDIO_HWLATENCY Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_RTAUDIO_HWLATENCY api_location: diff --git a/windows-driver-docs-pr/audio/ksproperty-rtaudio-packetcount.md b/windows-driver-docs-pr/audio/ksproperty-rtaudio-packetcount.md index bd98c043d8..569498e6b3 100644 --- a/windows-driver-docs-pr/audio/ksproperty-rtaudio-packetcount.md +++ b/windows-driver-docs-pr/audio/ksproperty-rtaudio-packetcount.md @@ -4,6 +4,7 @@ description: KSPROPERTY\_RTAUDIO\_PACKETCOUNT returns the (1-based) count of pac keywords: ["KSPROPERTY_RTAUDIO_PACKETCOUNT Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_RTAUDIO_PACKETCOUNT api_location: diff --git a/windows-driver-docs-pr/audio/ksproperty-rtaudio-positionregister.md b/windows-driver-docs-pr/audio/ksproperty-rtaudio-positionregister.md index 49c5a6acac..5136d3d838 100644 --- a/windows-driver-docs-pr/audio/ksproperty-rtaudio-positionregister.md +++ b/windows-driver-docs-pr/audio/ksproperty-rtaudio-positionregister.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_RTAUDIO\_POSITIONREGISTER property maps the positio keywords: ["KSPROPERTY_RTAUDIO_POSITIONREGISTER Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_RTAUDIO_POSITIONREGISTER api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_RTAUDIO\_POSITIONREGISTER diff --git a/windows-driver-docs-pr/audio/ksproperty-rtaudio-presentation-position.md b/windows-driver-docs-pr/audio/ksproperty-rtaudio-presentation-position.md index 9329478ee2..795fef6736 100644 --- a/windows-driver-docs-pr/audio/ksproperty-rtaudio-presentation-position.md +++ b/windows-driver-docs-pr/audio/ksproperty-rtaudio-presentation-position.md @@ -4,6 +4,7 @@ description: KSPROPERTY\_RTAUDIO\_PRESENTATION\_POSITION returns stream presenta keywords: ["KSPROPERTY_RTAUDIO_PRESENTATION_POSITION Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_RTAUDIO_PRESENTATION_POSITION api_location: diff --git a/windows-driver-docs-pr/audio/ksproperty-rtaudio-query-notification-support.md b/windows-driver-docs-pr/audio/ksproperty-rtaudio-query-notification-support.md index 77020cee18..f923d7ac51 100644 --- a/windows-driver-docs-pr/audio/ksproperty-rtaudio-query-notification-support.md +++ b/windows-driver-docs-pr/audio/ksproperty-rtaudio-query-notification-support.md @@ -4,15 +4,17 @@ description: The client application uses the KSPROPERTY\_RTAUDIO\_QUERY\_NOTIFIC keywords: ["KSPROPERTY_RTAUDIO_QUERY_NOTIFICATION_SUPPORT Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_RTAUDIO_QUERY_NOTIFICATION_SUPPORT api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_RTAUDIO\_QUERY\_NOTIFICATION\_SUPPORT diff --git a/windows-driver-docs-pr/audio/ksproperty-rtaudio-register-notification-event.md b/windows-driver-docs-pr/audio/ksproperty-rtaudio-register-notification-event.md index 61f68ad790..1bb6eaedb5 100644 --- a/windows-driver-docs-pr/audio/ksproperty-rtaudio-register-notification-event.md +++ b/windows-driver-docs-pr/audio/ksproperty-rtaudio-register-notification-event.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_RTAUDIO\_REGISTER\_NOTIFICATION\_EVENT property reg keywords: ["KSPROPERTY_RTAUDIO_REGISTER_NOTIFICATION_EVENT Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_RTAUDIO_REGISTER_NOTIFICATION_EVENT api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_RTAUDIO\_REGISTER\_NOTIFICATION\_EVENT diff --git a/windows-driver-docs-pr/audio/ksproperty-rtaudio-setwritepacket.md b/windows-driver-docs-pr/audio/ksproperty-rtaudio-setwritepacket.md index a8fa293a8d..4cddabf599 100644 --- a/windows-driver-docs-pr/audio/ksproperty-rtaudio-setwritepacket.md +++ b/windows-driver-docs-pr/audio/ksproperty-rtaudio-setwritepacket.md @@ -4,6 +4,7 @@ description: KSPROPERTY\_RTAUDIO\_SETWRITEPACKET informs the driver that the OS keywords: ["KSPROPERTY_RTAUDIO_SETWRITEPACKET Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_RTAUDIO_SETWRITEPACKET api_location: diff --git a/windows-driver-docs-pr/audio/ksproperty-rtaudio-unregister-notification-event.md b/windows-driver-docs-pr/audio/ksproperty-rtaudio-unregister-notification-event.md index 66934a0ae2..e7b257a541 100644 --- a/windows-driver-docs-pr/audio/ksproperty-rtaudio-unregister-notification-event.md +++ b/windows-driver-docs-pr/audio/ksproperty-rtaudio-unregister-notification-event.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_RTAUDIO\_UNREGISTER\_NOTIFICATION\_EVENT property u keywords: ["KSPROPERTY_RTAUDIO_UNREGISTER_NOTIFICATION_EVENT Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_RTAUDIO_UNREGISTER_NOTIFICATION_EVENT api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_RTAUDIO\_UNREGISTER\_NOTIFICATION\_EVENT diff --git a/windows-driver-docs-pr/audio/ksproperty-sounddetector-armed.md b/windows-driver-docs-pr/audio/ksproperty-sounddetector-armed.md index da1e46febe..c4d0a1e62e 100644 --- a/windows-driver-docs-pr/audio/ksproperty-sounddetector-armed.md +++ b/windows-driver-docs-pr/audio/ksproperty-sounddetector-armed.md @@ -4,6 +4,7 @@ description: The KSPROPERTY\_SOUNDDETECTOR\_ARMED property is the current arming keywords: ["KSPROPERTY_SOUNDDETECTOR_ARMED Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_SOUNDDETECTOR_ARMED api_location: diff --git a/windows-driver-docs-pr/audio/ksproperty-sounddetector-matchresult.md b/windows-driver-docs-pr/audio/ksproperty-sounddetector-matchresult.md index 6e0f089973..7999c4d7b2 100644 --- a/windows-driver-docs-pr/audio/ksproperty-sounddetector-matchresult.md +++ b/windows-driver-docs-pr/audio/ksproperty-sounddetector-matchresult.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_SOUNDDETECTOR\_MATCHRESULT property holds the resul keywords: ["KSPROPERTY_SOUNDDETECTOR_MATCHRESULT Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_SOUNDDETECTOR_MATCHRESULT api_location: - ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_SOUNDDETECTOR\_MATCHRESULT diff --git a/windows-driver-docs-pr/audio/ksproperty-sounddetector-patterns.md b/windows-driver-docs-pr/audio/ksproperty-sounddetector-patterns.md index a8ad4ed048..452650929b 100644 --- a/windows-driver-docs-pr/audio/ksproperty-sounddetector-patterns.md +++ b/windows-driver-docs-pr/audio/ksproperty-sounddetector-patterns.md @@ -4,6 +4,7 @@ description: The KSPROPERTY\_SOUNDDETECTOR\_PATTERNS property is set by the oper keywords: ["KSPROPERTY_SOUNDDETECTOR_PATTERNS Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_SOUNDDETECTOR_PATTERNS api_location: diff --git a/windows-driver-docs-pr/audio/ksproperty-sounddetector-reset.md b/windows-driver-docs-pr/audio/ksproperty-sounddetector-reset.md index 26a467f0c9..4fc86c526a 100644 --- a/windows-driver-docs-pr/audio/ksproperty-sounddetector-reset.md +++ b/windows-driver-docs-pr/audio/ksproperty-sounddetector-reset.md @@ -4,6 +4,7 @@ description: The KSPROPERTY\_SOUNDDETECTOR\_RESET property resets the detector t keywords: ["KSPROPERTY_SOUNDDETECTOR_RESET Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_SOUNDDETECTOR_RESET api_location: diff --git a/windows-driver-docs-pr/audio/ksproperty-sounddetector-streamingsupport.md b/windows-driver-docs-pr/audio/ksproperty-sounddetector-streamingsupport.md index d9b5d2048a..a28dcaf501 100644 --- a/windows-driver-docs-pr/audio/ksproperty-sounddetector-streamingsupport.md +++ b/windows-driver-docs-pr/audio/ksproperty-sounddetector-streamingsupport.md @@ -4,6 +4,7 @@ description: The KSPROPERTY\_SOUNDDETECTOR\_STREAMINGSUPPORT property indicates keywords: ["KSPROPERTY_SOUNDDETECTOR_STREAMINGSUPPORT Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_SOUNDDETECTOR_STREAMINGSUPPORT api_location: diff --git a/windows-driver-docs-pr/audio/ksproperty-sounddetector-supportedpatterns.md b/windows-driver-docs-pr/audio/ksproperty-sounddetector-supportedpatterns.md index e587704c3b..ee62b4ca3a 100644 --- a/windows-driver-docs-pr/audio/ksproperty-sounddetector-supportedpatterns.md +++ b/windows-driver-docs-pr/audio/ksproperty-sounddetector-supportedpatterns.md @@ -4,6 +4,7 @@ description: The KSPROPERTY\_SOUNDDETECTOR\_SUPPORTEDPATTERNS property is used t keywords: ["KSPROPERTY_SOUNDDETECTOR_SUPPORTEDPATTERNS Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_SOUNDDETECTOR_SUPPORTEDPATTERNS api_location: diff --git a/windows-driver-docs-pr/audio/ksproperty-sounddetector.md b/windows-driver-docs-pr/audio/ksproperty-sounddetector.md index 26e1de3f8b..5a74013457 100644 --- a/windows-driver-docs-pr/audio/ksproperty-sounddetector.md +++ b/windows-driver-docs-pr/audio/ksproperty-sounddetector.md @@ -4,23 +4,23 @@ description: The KSPROPERTY\_SOUNDDETECTOR enumeration defines constants that ar keywords: ["KSPROPERTY_SOUNDDETECTOR enumeration Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_SOUNDDETECTOR api_location: - ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- # KSPROPERTY\_SOUNDDETECTOR enumeration - The **KSPROPERTY\_SOUNDDETECTOR** enumeration defines constants that are used to register a filter for an audio capture device that also supports a detector. ## Syntax -```ManagedCPlusPlus +```cpp typedef enum { KSPROPERTY_SOUNDDETECTOR_SUPPORTEDPATTERNS  = 1, KSPROPERTY_SOUNDDETECTOR_PATTERNS, @@ -66,10 +66,9 @@ Specifies the ID for the [**KSPROPERTY\_SOUNDDETECTOR\_MATCHRESULT**](ksproperty -## See also - +## See also -[KSPROPSETID\_SoundDetector](kspropsetid-sounddetector.md) +[**KSPROPSETID\_SoundDetector**](kspropsetid-sounddetector.md) [**KSPROPERTY\_SOUNDDETECTOR\_SUPPORTEDPATTERNS**](ksproperty-sounddetector-supportedpatterns.md) @@ -78,13 +77,3 @@ Specifies the ID for the [**KSPROPERTY\_SOUNDDETECTOR\_MATCHRESULT**](ksproperty [**KSPROPERTY\_SOUNDDETECTOR\_ARMED**](ksproperty-sounddetector-armed.md) [**KSPROPERTY\_SOUNDDETECTOR\_MATCHRESULT**](ksproperty-sounddetector-matchresult.md) - - - - - - - - - - diff --git a/windows-driver-docs-pr/audio/ksproperty-sysaudio-attach-virtual-source.md b/windows-driver-docs-pr/audio/ksproperty-sysaudio-attach-virtual-source.md index f481689aa9..c0d2e910b7 100644 --- a/windows-driver-docs-pr/audio/ksproperty-sysaudio-attach-virtual-source.md +++ b/windows-driver-docs-pr/audio/ksproperty-sysaudio-attach-virtual-source.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_SYSAUDIO\_ATTACH\_VIRTUAL\_SOURCE property attaches keywords: ["KSPROPERTY_SYSAUDIO_ATTACH_VIRTUAL_SOURCE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_SYSAUDIO_ATTACH_VIRTUAL_SOURCE api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_SYSAUDIO\_ATTACH\_VIRTUAL\_SOURCE diff --git a/windows-driver-docs-pr/audio/ksproperty-sysaudio-component-id.md b/windows-driver-docs-pr/audio/ksproperty-sysaudio-component-id.md index b365f5f14f..f5b391496f 100644 --- a/windows-driver-docs-pr/audio/ksproperty-sysaudio-component-id.md +++ b/windows-driver-docs-pr/audio/ksproperty-sysaudio-component-id.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_SYSAUDIO\_COMPONENT\_ID property retrieves the comp keywords: ["KSPROPERTY_SYSAUDIO_COMPONENT_ID Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_SYSAUDIO_COMPONENT_ID api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_SYSAUDIO\_COMPONENT\_ID diff --git a/windows-driver-docs-pr/audio/ksproperty-sysaudio-create-virtual-source.md b/windows-driver-docs-pr/audio/ksproperty-sysaudio-create-virtual-source.md index eca5967f1b..3015f87102 100644 --- a/windows-driver-docs-pr/audio/ksproperty-sysaudio-create-virtual-source.md +++ b/windows-driver-docs-pr/audio/ksproperty-sysaudio-create-virtual-source.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_SYSAUDIO\_CREATE\_VIRTUAL\_SOURCE property creates keywords: ["KSPROPERTY_SYSAUDIO_CREATE_VIRTUAL_SOURCE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_SYSAUDIO_CREATE_VIRTUAL_SOURCE api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_SYSAUDIO\_CREATE\_VIRTUAL\_SOURCE diff --git a/windows-driver-docs-pr/audio/ksproperty-sysaudio-device-count.md b/windows-driver-docs-pr/audio/ksproperty-sysaudio-device-count.md index cf5c66be80..01e57a01dc 100644 --- a/windows-driver-docs-pr/audio/ksproperty-sysaudio-device-count.md +++ b/windows-driver-docs-pr/audio/ksproperty-sysaudio-device-count.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_SYSAUDIO\_DEVICE\_COUNT property retrieves a count keywords: ["KSPROPERTY_SYSAUDIO_DEVICE_COUNT Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_SYSAUDIO_DEVICE_COUNT api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_SYSAUDIO\_DEVICE\_COUNT diff --git a/windows-driver-docs-pr/audio/ksproperty-sysaudio-device-friendly-name.md b/windows-driver-docs-pr/audio/ksproperty-sysaudio-device-friendly-name.md index f638044fdc..e23108f830 100644 --- a/windows-driver-docs-pr/audio/ksproperty-sysaudio-device-friendly-name.md +++ b/windows-driver-docs-pr/audio/ksproperty-sysaudio-device-friendly-name.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_SYSAUDIO\_DEVICE\_FRIENDLY\_NAME property retrieves keywords: ["KSPROPERTY_SYSAUDIO_DEVICE_FRIENDLY_NAME Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_SYSAUDIO_DEVICE_FRIENDLY_NAME api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_SYSAUDIO\_DEVICE\_FRIENDLY\_NAME diff --git a/windows-driver-docs-pr/audio/ksproperty-sysaudio-device-instance.md b/windows-driver-docs-pr/audio/ksproperty-sysaudio-device-instance.md index 095a4d19f6..fd2ac0c044 100644 --- a/windows-driver-docs-pr/audio/ksproperty-sysaudio-device-instance.md +++ b/windows-driver-docs-pr/audio/ksproperty-sysaudio-device-instance.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_SYSAUDIO\_DEVICE\_INSTANCE property specifies the c keywords: ["KSPROPERTY_SYSAUDIO_DEVICE_INSTANCE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_SYSAUDIO_DEVICE_INSTANCE api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_SYSAUDIO\_DEVICE\_INSTANCE diff --git a/windows-driver-docs-pr/audio/ksproperty-sysaudio-device-interface-name.md b/windows-driver-docs-pr/audio/ksproperty-sysaudio-device-interface-name.md index 49ba71d6e0..921444dd32 100644 --- a/windows-driver-docs-pr/audio/ksproperty-sysaudio-device-interface-name.md +++ b/windows-driver-docs-pr/audio/ksproperty-sysaudio-device-interface-name.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_SYSAUDIO\_DEVICE\_INTERFACE\_NAME property retrieve keywords: ["KSPROPERTY_SYSAUDIO_DEVICE_INTERFACE_NAME Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_SYSAUDIO_DEVICE_INTERFACE_NAME api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_SYSAUDIO\_DEVICE\_INTERFACE\_NAME diff --git a/windows-driver-docs-pr/audio/ksproperty-sysaudio-instance-info.md b/windows-driver-docs-pr/audio/ksproperty-sysaudio-instance-info.md index af8df64c42..bf589df763 100644 --- a/windows-driver-docs-pr/audio/ksproperty-sysaudio-instance-info.md +++ b/windows-driver-docs-pr/audio/ksproperty-sysaudio-instance-info.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_SYSAUDIO\_INSTANCE\_INFO property opens a virtual a keywords: ["KSPROPERTY_SYSAUDIO_INSTANCE_INFO Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_SYSAUDIO_INSTANCE_INFO api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_SYSAUDIO\_INSTANCE\_INFO diff --git a/windows-driver-docs-pr/audio/ksproperty-sysaudio-select-graph.md b/windows-driver-docs-pr/audio/ksproperty-sysaudio-select-graph.md index de2098fb53..9dbe8004ab 100644 --- a/windows-driver-docs-pr/audio/ksproperty-sysaudio-select-graph.md +++ b/windows-driver-docs-pr/audio/ksproperty-sysaudio-select-graph.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_SYSAUDIO\_SELECT\_GRAPH property is used to explici keywords: ["KSPROPERTY_SYSAUDIO_SELECT_GRAPH Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_SYSAUDIO_SELECT_GRAPH api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_SYSAUDIO\_SELECT\_GRAPH diff --git a/windows-driver-docs-pr/audio/ksproperty-telephony-callcontrol.md b/windows-driver-docs-pr/audio/ksproperty-telephony-callcontrol.md index 3803b8d887..ce7adae41d 100644 --- a/windows-driver-docs-pr/audio/ksproperty-telephony-callcontrol.md +++ b/windows-driver-docs-pr/audio/ksproperty-telephony-callcontrol.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_TELEPHONY\_CALLCONTROL property is used to start an keywords: ["KSPROPERTY_TELEPHONY_CALLCONTROL Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_TELEPHONY_CALLCONTROL api_location: - ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_TELEPHONY\_CALLCONTROL diff --git a/windows-driver-docs-pr/audio/ksproperty-telephony-callhold.md b/windows-driver-docs-pr/audio/ksproperty-telephony-callhold.md index 5c236c4723..c2cf300505 100644 --- a/windows-driver-docs-pr/audio/ksproperty-telephony-callhold.md +++ b/windows-driver-docs-pr/audio/ksproperty-telephony-callhold.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_TELEPHONY\_CALLHOLD property is used to control the keywords: ["KSPROPERTY_TELEPHONY_CALLHOLD Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_TELEPHONY_CALLHOLD api_location: - ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_TELEPHONY\_CALLHOLD diff --git a/windows-driver-docs-pr/audio/ksproperty-telephony-callinfo.md b/windows-driver-docs-pr/audio/ksproperty-telephony-callinfo.md index 4526e52a1a..a3f22ccf10 100644 --- a/windows-driver-docs-pr/audio/ksproperty-telephony-callinfo.md +++ b/windows-driver-docs-pr/audio/ksproperty-telephony-callinfo.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_TELEPHONY\_CALLINFO property is used to retrieve cu keywords: ["KSPROPERTY_TELEPHONY_CALLINFO Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_TELEPHONY_CALLINFO api_location: - ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_TELEPHONY\_CALLINFO diff --git a/windows-driver-docs-pr/audio/ksproperty-telephony-endpointidpair.md b/windows-driver-docs-pr/audio/ksproperty-telephony-endpointidpair.md index e699b575d7..73ff1cac5f 100644 --- a/windows-driver-docs-pr/audio/ksproperty-telephony-endpointidpair.md +++ b/windows-driver-docs-pr/audio/ksproperty-telephony-endpointidpair.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_TELEPHONY\_ENDPOINTIDPAIR property contains the ren keywords: ["KSPROPERTY_TELEPHONY_ENDPOINTIDPAIR Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_TELEPHONY_ENDPOINTIDPAIR api_location: - ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_TELEPHONY\_ENDPOINTIDPAIR diff --git a/windows-driver-docs-pr/audio/ksproperty-telephony-mute-tx.md b/windows-driver-docs-pr/audio/ksproperty-telephony-mute-tx.md index 5ab2fab7bd..253f00a35d 100644 --- a/windows-driver-docs-pr/audio/ksproperty-telephony-mute-tx.md +++ b/windows-driver-docs-pr/audio/ksproperty-telephony-mute-tx.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_TELEPHONY\_MUTE\_TX property is used to control whe keywords: ["KSPROPERTY_TELEPHONY_MUTE_TX Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_TELEPHONY_MUTE_TX api_location: - ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_TELEPHONY\_MUTE\_TX diff --git a/windows-driver-docs-pr/audio/ksproperty-telephony-providerchange.md b/windows-driver-docs-pr/audio/ksproperty-telephony-providerchange.md index 39feed1768..79624540c1 100644 --- a/windows-driver-docs-pr/audio/ksproperty-telephony-providerchange.md +++ b/windows-driver-docs-pr/audio/ksproperty-telephony-providerchange.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_TELEPHONY\_PROVIDERCHANGE property is used to commu keywords: ["KSPROPERTY_TELEPHONY_PROVIDERCHANGE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_TELEPHONY_PROVIDERCHANGE api_location: - ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_TELEPHONY\_PROVIDERCHANGE diff --git a/windows-driver-docs-pr/audio/ksproperty-telephony-providerid.md b/windows-driver-docs-pr/audio/ksproperty-telephony-providerid.md index 18b2c63a51..f4beaaa62e 100644 --- a/windows-driver-docs-pr/audio/ksproperty-telephony-providerid.md +++ b/windows-driver-docs-pr/audio/ksproperty-telephony-providerid.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_TELEPHONY\_PROVIDERID property is used by the audio keywords: ["KSPROPERTY_TELEPHONY_PROVIDERID Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_TELEPHONY_PROVIDERID api_location: - ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_TELEPHONY\_PROVIDERID diff --git a/windows-driver-docs-pr/audio/ksproperty-telephony-volume.md b/windows-driver-docs-pr/audio/ksproperty-telephony-volume.md index 790ee48fec..1ffe254935 100644 --- a/windows-driver-docs-pr/audio/ksproperty-telephony-volume.md +++ b/windows-driver-docs-pr/audio/ksproperty-telephony-volume.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_TELEPHONY\_VOLUME property is used to control the v keywords: ["KSPROPERTY_TELEPHONY_VOLUME Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_TELEPHONY_VOLUME api_location: - ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_TELEPHONY\_VOLUME diff --git a/windows-driver-docs-pr/audio/ksproperty-topologynode-enable.md b/windows-driver-docs-pr/audio/ksproperty-topologynode-enable.md index 323b5341c4..49244f5ea1 100644 --- a/windows-driver-docs-pr/audio/ksproperty-topologynode-enable.md +++ b/windows-driver-docs-pr/audio/ksproperty-topologynode-enable.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_TOPOLOGYNODE\_ENABLE property is used to turn on or keywords: ["KSPROPERTY_TOPOLOGYNODE_ENABLE Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_TOPOLOGYNODE_ENABLE api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_TOPOLOGYNODE\_ENABLE diff --git a/windows-driver-docs-pr/audio/ksproperty-topologynode-reset.md b/windows-driver-docs-pr/audio/ksproperty-topologynode-reset.md index 6fbdbde516..97ef711cf2 100644 --- a/windows-driver-docs-pr/audio/ksproperty-topologynode-reset.md +++ b/windows-driver-docs-pr/audio/ksproperty-topologynode-reset.md @@ -4,15 +4,17 @@ description: The KSPROPERTY\_TOPOLOGYNODE\_RESET property resets the node comple keywords: ["KSPROPERTY_TOPOLOGYNODE_RESET Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSPROPERTY_TOPOLOGYNODE_RESET api_location: - Ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPERTY\_TOPOLOGYNODE\_RESET diff --git a/windows-driver-docs-pr/audio/kspropsetid-ac3.md b/windows-driver-docs-pr/audio/kspropsetid-ac3.md index 073c9aeac3..84e6b7e3fc 100644 --- a/windows-driver-docs-pr/audio/kspropsetid-ac3.md +++ b/windows-driver-docs-pr/audio/kspropsetid-ac3.md @@ -2,9 +2,10 @@ title: KSPROPSETID\_AC3 description: KSPROPSETID\_AC3 keywords: ["KSPROPSETID_AC3"] -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSPROPSETID\_AC3 diff --git a/windows-driver-docs-pr/audio/kspropsetid-acoustic-echo-cancel.md b/windows-driver-docs-pr/audio/kspropsetid-acoustic-echo-cancel.md index 40ec8a92e1..97d5099114 100644 --- a/windows-driver-docs-pr/audio/kspropsetid-acoustic-echo-cancel.md +++ b/windows-driver-docs-pr/audio/kspropsetid-acoustic-echo-cancel.md @@ -2,9 +2,11 @@ title: KSPROPSETID\_Acoustic\_Echo\_Cancel description: KSPROPSETID\_Acoustic\_Echo\_Cancel keywords: ["KSPROPSETID_Acoustic_Echo_Cancel"] -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # KSPROPSETID\_Acoustic\_Echo\_Cancel diff --git a/windows-driver-docs-pr/audio/kspropsetid-audio.md b/windows-driver-docs-pr/audio/kspropsetid-audio.md index bf7cacf01a..0aef7866f3 100644 --- a/windows-driver-docs-pr/audio/kspropsetid-audio.md +++ b/windows-driver-docs-pr/audio/kspropsetid-audio.md @@ -2,9 +2,11 @@ title: KSPROPSETID\_Audio description: KSPROPSETID\_Audio keywords: ["KSPROPSETID_Audio"] -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # KSPROPSETID\_Audio diff --git a/windows-driver-docs-pr/audio/kspropsetid-audioeffectsdiscovery.md b/windows-driver-docs-pr/audio/kspropsetid-audioeffectsdiscovery.md index 9fa5d802b8..d156f260e3 100644 --- a/windows-driver-docs-pr/audio/kspropsetid-audioeffectsdiscovery.md +++ b/windows-driver-docs-pr/audio/kspropsetid-audioeffectsdiscovery.md @@ -1,9 +1,11 @@ --- title: KSPROPSETID\_AudioEffectsDiscovery description: The KSPROPSETID\_AudioEffectsDiscovery property set is implemented by audio device drivers that use Microsoft’s generic proxy audio processing object (APO). -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # KSPROPSETID\_AudioEffectsDiscovery diff --git a/windows-driver-docs-pr/audio/kspropsetid-audioengine.md b/windows-driver-docs-pr/audio/kspropsetid-audioengine.md index aa772809c0..1ed815fa82 100644 --- a/windows-driver-docs-pr/audio/kspropsetid-audioengine.md +++ b/windows-driver-docs-pr/audio/kspropsetid-audioengine.md @@ -1,9 +1,11 @@ --- title: KSPROPSETID\_AudioEngine description: The KSPROPSETID\_AudioEngine property set contains KS properties that the audio driver can use to provide more information about the hardware audio engine node. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # KSPROPSETID\_AudioEngine diff --git a/windows-driver-docs-pr/audio/kspropsetid-audiogfx.md b/windows-driver-docs-pr/audio/kspropsetid-audiogfx.md index 011a5853db..27141c3097 100644 --- a/windows-driver-docs-pr/audio/kspropsetid-audiogfx.md +++ b/windows-driver-docs-pr/audio/kspropsetid-audiogfx.md @@ -2,9 +2,11 @@ title: KSPROPSETID\_AudioGfx description: KSPROPSETID\_AudioGfx keywords: ["KSPROPSETID_AudioGfx"] -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # KSPROPSETID\_AudioGfx diff --git a/windows-driver-docs-pr/audio/kspropsetid-audiomodule.md b/windows-driver-docs-pr/audio/kspropsetid-audiomodule.md index 130e664660..e47b8c0178 100644 --- a/windows-driver-docs-pr/audio/kspropsetid-audiomodule.md +++ b/windows-driver-docs-pr/audio/kspropsetid-audiomodule.md @@ -1,9 +1,11 @@ --- title: KSPROPSETID\_AudioModule description: The KSPROPSETID\_AudioModule property set is used by the audio driver to retrieve the list of audio modules. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # KSPROPSETID\_AudioModule diff --git a/windows-driver-docs-pr/audio/kspropsetid-audiosignalprocessing.md b/windows-driver-docs-pr/audio/kspropsetid-audiosignalprocessing.md index 10d3db8080..5634e8d484 100644 --- a/windows-driver-docs-pr/audio/kspropsetid-audiosignalprocessing.md +++ b/windows-driver-docs-pr/audio/kspropsetid-audiosignalprocessing.md @@ -1,9 +1,11 @@ --- title: KSPROPSETID\_AudioSignalProcessing description: The KSPROPSETID\_AudioSignalProcessing property set is used by the audio driver to retrieve the list of audio signal processing modes supported by a pin factory. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # KSPROPSETID\_AudioSignalProcessing diff --git a/windows-driver-docs-pr/audio/kspropsetid-btaudio.md b/windows-driver-docs-pr/audio/kspropsetid-btaudio.md index ea92b035de..2ec7cc86a7 100644 --- a/windows-driver-docs-pr/audio/kspropsetid-btaudio.md +++ b/windows-driver-docs-pr/audio/kspropsetid-btaudio.md @@ -1,9 +1,11 @@ --- title: KSPROPSETID\_BtAudio description: KSPROPSETID\_BtAudio -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # KSPROPSETID\_BtAudio diff --git a/windows-driver-docs-pr/audio/kspropsetid-directsound3dbuffer.md b/windows-driver-docs-pr/audio/kspropsetid-directsound3dbuffer.md index 1f6e9c38d8..e417b45770 100644 --- a/windows-driver-docs-pr/audio/kspropsetid-directsound3dbuffer.md +++ b/windows-driver-docs-pr/audio/kspropsetid-directsound3dbuffer.md @@ -2,9 +2,11 @@ title: KSPROPSETID\_DirectSound3DBuffer description: KSPROPSETID\_DirectSound3DBuffer keywords: ["KSPROPSETID_DirectSound3DBuffer"] -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # KSPROPSETID\_DirectSound3DBuffer diff --git a/windows-driver-docs-pr/audio/kspropsetid-directsound3dlistener.md b/windows-driver-docs-pr/audio/kspropsetid-directsound3dlistener.md index e5fbbf632e..74ebbf6637 100644 --- a/windows-driver-docs-pr/audio/kspropsetid-directsound3dlistener.md +++ b/windows-driver-docs-pr/audio/kspropsetid-directsound3dlistener.md @@ -2,9 +2,11 @@ title: KSPROPSETID\_DirectSound3DListener description: KSPROPSETID\_DirectSound3DListener keywords: ["KSPROPSETID_DirectSound3DListener"] -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # KSPROPSETID\_DirectSound3DListener diff --git a/windows-driver-docs-pr/audio/kspropsetid-drmaudiostream.md b/windows-driver-docs-pr/audio/kspropsetid-drmaudiostream.md index d67c35c69b..555a4d6971 100644 --- a/windows-driver-docs-pr/audio/kspropsetid-drmaudiostream.md +++ b/windows-driver-docs-pr/audio/kspropsetid-drmaudiostream.md @@ -2,9 +2,11 @@ title: KSPROPSETID\_DrmAudioStream description: KSPROPSETID\_DrmAudioStream keywords: ["KSPROPSETID_DrmAudioStream"] -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # KSPROPSETID\_DrmAudioStream diff --git a/windows-driver-docs-pr/audio/kspropsetid-fmrxcontrol.md b/windows-driver-docs-pr/audio/kspropsetid-fmrxcontrol.md index 0e61a9c4d6..49f6140d1b 100644 --- a/windows-driver-docs-pr/audio/kspropsetid-fmrxcontrol.md +++ b/windows-driver-docs-pr/audio/kspropsetid-fmrxcontrol.md @@ -1,9 +1,11 @@ --- title: KSPROPSETID\_FMRXControl description: The KSPROPSETID\_FMRXControl property set is used to control whether FM radio reception is enabled. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # KSPROPSETID\_FMRXControl diff --git a/windows-driver-docs-pr/audio/kspropsetid-fmrxtopology.md b/windows-driver-docs-pr/audio/kspropsetid-fmrxtopology.md index 0ccc683cca..1d4dfbc473 100644 --- a/windows-driver-docs-pr/audio/kspropsetid-fmrxtopology.md +++ b/windows-driver-docs-pr/audio/kspropsetid-fmrxtopology.md @@ -1,9 +1,11 @@ --- title: KSPROPSETID\_FMRXTopology description: The KSPROPSETID\_FMRXTopology property set is used to set FM radio properties. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # KSPROPSETID\_FMRXTopology diff --git a/windows-driver-docs-pr/audio/kspropsetid-hrtf3d.md b/windows-driver-docs-pr/audio/kspropsetid-hrtf3d.md index fd686b8647..2120ae50e8 100644 --- a/windows-driver-docs-pr/audio/kspropsetid-hrtf3d.md +++ b/windows-driver-docs-pr/audio/kspropsetid-hrtf3d.md @@ -2,9 +2,11 @@ title: KSPROPSETID\_Hrtf3d description: KSPROPSETID\_Hrtf3d keywords: ["KSPROPSETID_Hrtf3d"] -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # KSPROPSETID\_Hrtf3d diff --git a/windows-driver-docs-pr/audio/kspropsetid-itd3d.md b/windows-driver-docs-pr/audio/kspropsetid-itd3d.md index 646f05dcc5..616b28c4b6 100644 --- a/windows-driver-docs-pr/audio/kspropsetid-itd3d.md +++ b/windows-driver-docs-pr/audio/kspropsetid-itd3d.md @@ -2,9 +2,11 @@ title: KSPROPSETID\_Itd3d description: KSPROPSETID\_Itd3d keywords: ["KSPROPSETID_Itd3d"] -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # KSPROPSETID\_Itd3d diff --git a/windows-driver-docs-pr/audio/kspropsetid-jack.md b/windows-driver-docs-pr/audio/kspropsetid-jack.md index 696262c33c..a7be6b4da0 100644 --- a/windows-driver-docs-pr/audio/kspropsetid-jack.md +++ b/windows-driver-docs-pr/audio/kspropsetid-jack.md @@ -1,9 +1,11 @@ --- title: KSPROPSETID\_Jack description: KSPROPSETID\_Jack -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # KSPROPSETID\_Jack @@ -15,6 +17,8 @@ The `KSPROPSETID_Jack` property set includes the [**KSPROPERTY\_JACK**](ksproper [**KSPROPERTY\_JACK\_DESCRIPTION2**](ksproperty-jack-description2.md) +[**KSPROPERTY\_JACK\_DESCRIPTION3**](ksproperty-jack-description3.md) + [**KSPROPERTY\_JACK\_SINK\_INFO**](ksproperty-jack-sink-info.md) [**KSPROPERTY\_JACK\_CONTAINERID**](ksproperty-jack-containerid.md) diff --git a/windows-driver-docs-pr/audio/kspropsetid-rtaudio.md b/windows-driver-docs-pr/audio/kspropsetid-rtaudio.md index 0327dd5689..bd1703cc4c 100644 --- a/windows-driver-docs-pr/audio/kspropsetid-rtaudio.md +++ b/windows-driver-docs-pr/audio/kspropsetid-rtaudio.md @@ -1,9 +1,11 @@ --- title: KSPROPSETID\_RTAudio description: KSPROPSETID\_RTAudio -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # KSPROPSETID\_RTAudio diff --git a/windows-driver-docs-pr/audio/kspropsetid-sounddetector.md b/windows-driver-docs-pr/audio/kspropsetid-sounddetector.md index 0a7c07b3e0..f4023e38f4 100644 --- a/windows-driver-docs-pr/audio/kspropsetid-sounddetector.md +++ b/windows-driver-docs-pr/audio/kspropsetid-sounddetector.md @@ -1,9 +1,11 @@ --- title: KSPROPSETID\_SoundDetector description: Learn about the 'KSPROPSETID_SoundDetector' property set. This set includes 'KSPROPERTY\_SOUNDDETECTOR\_ARMED' and '\_PATTERNS', and \_MATCHRESULT properties. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # KSPROPSETID\_SoundDetector diff --git a/windows-driver-docs-pr/audio/kspropsetid-synth-dls.md b/windows-driver-docs-pr/audio/kspropsetid-synth-dls.md index 4de3819909..71db87c403 100644 --- a/windows-driver-docs-pr/audio/kspropsetid-synth-dls.md +++ b/windows-driver-docs-pr/audio/kspropsetid-synth-dls.md @@ -2,9 +2,11 @@ title: KSPROPSETID\_Synth\_Dls description: KSPROPSETID\_Synth\_Dls keywords: ["KSPROPSETID_Synth_Dls"] -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # KSPROPSETID\_Synth\_Dls diff --git a/windows-driver-docs-pr/audio/kspropsetid-synth.md b/windows-driver-docs-pr/audio/kspropsetid-synth.md index de526581fd..eabc115473 100644 --- a/windows-driver-docs-pr/audio/kspropsetid-synth.md +++ b/windows-driver-docs-pr/audio/kspropsetid-synth.md @@ -2,9 +2,11 @@ title: KSPROPSETID\_Synth description: KSPROPSETID\_Synth keywords: ["KSPROPSETID_Synth"] -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # KSPROPSETID\_Synth diff --git a/windows-driver-docs-pr/audio/kspropsetid-synthclock.md b/windows-driver-docs-pr/audio/kspropsetid-synthclock.md index 556205404b..5333c87421 100644 --- a/windows-driver-docs-pr/audio/kspropsetid-synthclock.md +++ b/windows-driver-docs-pr/audio/kspropsetid-synthclock.md @@ -2,9 +2,11 @@ title: KSPROPSETID\_SynthClock description: KSPROPSETID\_SynthClock keywords: ["KSPROPSETID_SynthClock"] -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # KSPROPSETID\_SynthClock diff --git a/windows-driver-docs-pr/audio/kspropsetid-sysaudio-pin.md b/windows-driver-docs-pr/audio/kspropsetid-sysaudio-pin.md index 1247179085..49765669d9 100644 --- a/windows-driver-docs-pr/audio/kspropsetid-sysaudio-pin.md +++ b/windows-driver-docs-pr/audio/kspropsetid-sysaudio-pin.md @@ -2,9 +2,11 @@ title: KSPROPSETID\_Sysaudio\_Pin description: KSPROPSETID\_Sysaudio\_Pin keywords: ["KSPROPSETID_Sysaudio_Pin"] -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # KSPROPSETID\_Sysaudio\_Pin diff --git a/windows-driver-docs-pr/audio/kspropsetid-sysaudio.md b/windows-driver-docs-pr/audio/kspropsetid-sysaudio.md index 5dcc5d960a..ff72cc4d68 100644 --- a/windows-driver-docs-pr/audio/kspropsetid-sysaudio.md +++ b/windows-driver-docs-pr/audio/kspropsetid-sysaudio.md @@ -2,9 +2,11 @@ title: KSPROPSETID\_Sysaudio description: KSPROPSETID\_Sysaudio keywords: ["KSPROPSETID_Sysaudio"] -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # KSPROPSETID\_Sysaudio diff --git a/windows-driver-docs-pr/audio/kspropsetid-telephonycontrol.md b/windows-driver-docs-pr/audio/kspropsetid-telephonycontrol.md index de296dd770..73113cb3bd 100644 --- a/windows-driver-docs-pr/audio/kspropsetid-telephonycontrol.md +++ b/windows-driver-docs-pr/audio/kspropsetid-telephonycontrol.md @@ -1,9 +1,11 @@ --- title: KSPROPSETID\_TelephonyControl description: The KSPROPSETID\_TelephonyControl property set is used to work with telephony control properties. These properties can be used to determine the state of a call and perform certain operations such as putting a call on hold or muting the local microphone. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # KSPROPSETID\_TelephonyControl diff --git a/windows-driver-docs-pr/audio/kspropsetid-telephonytopology.md b/windows-driver-docs-pr/audio/kspropsetid-telephonytopology.md index 19a2cbca35..727027f9ae 100644 --- a/windows-driver-docs-pr/audio/kspropsetid-telephonytopology.md +++ b/windows-driver-docs-pr/audio/kspropsetid-telephonytopology.md @@ -1,9 +1,11 @@ --- title: KSPROPSETID\_TelephonyTopology description: The KSPROPSETID\_TelephonyTopology property set is used access endpoints associated with cellular audio routing as well as the cellular call volume. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # KSPROPSETID\_TelephonyTopology diff --git a/windows-driver-docs-pr/audio/kspropsetid-topologynode.md b/windows-driver-docs-pr/audio/kspropsetid-topologynode.md index ee437243d2..08e5ffa541 100644 --- a/windows-driver-docs-pr/audio/kspropsetid-topologynode.md +++ b/windows-driver-docs-pr/audio/kspropsetid-topologynode.md @@ -2,9 +2,11 @@ title: KSPROPSETID\_TopologyNode description: KSPROPSETID\_TopologyNode keywords: ["KSPROPSETID_TopologyNode"] -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # KSPROPSETID\_TopologyNode diff --git a/windows-driver-docs-pr/audio/ksrtaudio-buffer-property.md b/windows-driver-docs-pr/audio/ksrtaudio-buffer-property.md index c4b608dff8..b85d4571b0 100644 --- a/windows-driver-docs-pr/audio/ksrtaudio-buffer-property.md +++ b/windows-driver-docs-pr/audio/ksrtaudio-buffer-property.md @@ -4,15 +4,17 @@ description: The KSRTAUDIO\_BUFFER\_PROPERTY structure appends a buffer base add keywords: ["KSRTAUDIO_BUFFER_PROPERTY structure Audio Devices", "PKSRTAUDIO_BUFFER_PROPERTY structure pointer Audio Devices"] topic_type: - apiref +ms.topic: reference api_name: - KSRTAUDIO_BUFFER_PROPERTY api_location: - ksmedia.h api_type: - HeaderDef -ms.date: 11/28/2017 +ms.date: 03/06/2023 --- + # KSRTAUDIO\_BUFFER\_PROPERTY structure @@ -20,7 +22,7 @@ The KSRTAUDIO\_BUFFER\_PROPERTY structure appends a buffer base address and requ ## Syntax -```ManagedCPlusPlus +```cpp typedef struct { KSPROPERTY Property; PVOID      BaseAddress; diff --git a/windows-driver-docs-pr/audio/legacy-audio-device-messages.md b/windows-driver-docs-pr/audio/legacy-audio-device-messages.md index 9981070a71..efc87baf0d 100644 --- a/windows-driver-docs-pr/audio/legacy-audio-device-messages.md +++ b/windows-driver-docs-pr/audio/legacy-audio-device-messages.md @@ -1,9 +1,11 @@ --- title: Legacy Audio Device Messages description: Legacy Audio Device Messages -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # Legacy Audio Device Messages diff --git a/windows-driver-docs-pr/audio/low-latency-audio.md b/windows-driver-docs-pr/audio/low-latency-audio.md index 2f844d8b03..b83831411a 100644 --- a/windows-driver-docs-pr/audio/low-latency-audio.md +++ b/windows-driver-docs-pr/audio/low-latency-audio.md @@ -1,132 +1,132 @@ --- title: Low Latency Audio -description: This topic discusses audio latency changes in Windows 10. It covers API options for application developers as well as changes in drivers that can be made to support low latency audio. -ms.date: 01/19/2021 +description: This article discusses audio latency changes in Windows 10. It covers API options for application developers and changes in drivers that can be made to support low latency audio. +ms.date: 10/28/2022 --- # Low Latency Audio -This topic discusses audio latency changes in Windows 10. It covers API options for application developers as well as changes in drivers that can be made to support low latency audio. +This article discusses audio latency changes in Windows 10. It covers API options for application developers and changes in drivers that can be made to support low latency audio. Audio latency is the delay between that time that sound is created and when it's heard. Having low audio latency is important for several key scenarios, such as: -## Overview - -Audio latency is the delay between that time that sound is created and when it is heard. Having low audio latency is very important for several key scenarios, such as the following. - -- Pro Audio -- Music Creation +- Pro audio +- Music creation - Communications -- Virtual Reality +- Virtual reality - Games -Windows 10 includes changes to reduce the audio latency. The goals of this document are to: +The goals of this document are to: 1. Describe the sources of audio latency in Windows. -2. Explain the changes that reduce audio latency in the Windows 10 audio stack. -3. Provide a reference on how application developers and hardware manufacturers can take advantage of the new infrastructure, in order to develop applications and drivers with low audio latency. This topic covers these items: -4. The new [**AudioGraph**](/uwp/api/Windows.Media.Audio.AudioGraph) API for interactive and media creation scenarios. -5. Changes in WASAPI to support low latency. -6. Enhancements in the driver DDIs. +1. Explain the changes that reduce audio latency in the Windows 10 audio stack. +1. Provide a reference on how application developers and hardware manufacturers can take advantage of the new infrastructure, in order to develop applications and drivers with low audio latency. + +This article covers: + +1. The new **[AudioGraph](/uwp/api/Windows.Media.Audio.AudioGraph)** API for interactive and media creation scenarios. +1. Changes in WASAPI to support low latency. +1. Enhancements in the driver DDIs. -## Definitions +## Terminology -|Term|Description| -|--- |--- | -|Render latency|Delay between the time that an application submits a buffer of audio data to the render APIs, until the time that it is heard from the speakers.| -|Capture latency|Delay between the time that a sound is captured from the microphone, until the time that it is sent to the capture APIs that are being used by the application.| -|Roundtrip latency|Delay between the time that a sound is captured from the microphone, processed by the application and submitted by the application for rendering to the speakers. It is roughly equal to render latency + capture latency.| -|Touch-to-app latency|Delay between the time that a user taps the screen until the time that the signal is sent to the application.| -|Touch-to-sound latency|Delay between the time that a user taps the screen, the event goes to the application and a sound is heard via the speakers. It is equal to render latency + touch-to-app latency.| +| Term | Description | +|---|---| +| Render latency | Delay between the time that an application submits a buffer of audio data to the render APIs, until the time that it's heard from the speakers. | +| Capture latency | Delay between the time that a sound is captured from the microphone, until the time it's sent to the capture APIs that are being used by the application. | +| Roundtrip latency | Delay between the time that a sound is captured from the microphone, processed by the application and submitted by the application for rendering to the speakers. It's roughly equal to render latency + capture latency. | +| Touch-to-app latency | Delay between the time that a user taps the screen until the time that the signal is sent to the application. | +| Touch-to-sound latency | Delay between the time that a user taps the screen, the event goes to the application and a sound is heard via the speakers. It's equal to render latency + touch-to-app latency. | -## Windows Audio Stack +## Windows audio stack The following diagram shows a simplified version of the Windows audio stack. -![low latency audio stack diagram showing apps, audio engine driver and h/w.](images/low-latency-audio-stack-diagram-1.png) +:::image type="content" source="images/low-latency-audio-stack-diagram-1.png" alt-text="Diagram of the low latency audio stack showing apps, audio engine driver, and hardware."::: -Here is a summary of the latencies in the render path: +Here's a summary of the latencies in the render path: +audio processing objects 1. The application writes the data into a buffer -2. The Audio Engine reads the data from the buffer and processes it. It also loads audio effects in the form of Audio Processing Objects (APOs). For more information about APOs, see [Windows Audio Processing Objects](windows-audio-processing-objects.md). -3. The latency of the APOs varies based on the signal processing within the APOs. -4. Before Windows 10, the latency of the Audio Engine was equal to ~12ms for applications that use floating point data and ~6ms for applications that use integer data -5. In Windows 10, the latency has been reduced to 1.3ms for all applications +1. The audio engine reads the data from the buffer and processes it. It also loads audio effects in the form of audio processing objects (APOs). For more information about APOs, see [Windows audio processing objects](windows-audio-processing-objects.md). +1. The latency of the APOs varies based on the signal processing within the APOs. +1. Before Windows 10, the latency of the audio engine was equal to ~12 ms for applications that use floating point data and ~6 ms for applications that use integer data +1. In Windows 10 and later, the latency has been reduced to 1.3 ms for all applications -6. The Audio Engine writes the processed data to a buffer. -7. Before Windows 10, this buffer was always set to ~10ms. -8. Starting with Windows 10, the buffer size is defined by the audio driver (more details on this are described later in this topic). +1. The audio engine writes the processed data to a buffer. +1. Before Windows 10, the buffer was always set to ~10 ms. +1. Starting with Windows 10, the buffer size is defined by the audio driver (more details on the buffer are described later in this article). -9. The Audio driver reads the data from the buffer and writes them to the H/W. -10. The H/W also has the option to process the data again (in the form of additional audio effects). -11. The user hears audio from the speaker. +1. The Audio driver reads the data from the buffer and writes them to the hardware. +1. The hardware can also process the data again in the form of more audio effects. +1. The user hears audio from the speaker. -Here is a summary of latency in the capture path: +Here's a summary of latency in the capture path: 1. Audio is captured from the microphone. -2. The H/W has the option to process the data (i.e. to add audio effects). -3. The driver reads the data from the H/W and writes the data into a buffer. -4. Before Windows 10, this buffer was always set to 10ms. -5. Starting with Windows 10, the buffer size is defined by the audio driver (more details on this below). +1. The hardware can process the data. For example, to add audio effects. +1. The driver reads the data from the hardware and writes the data into a buffer. +1. Before Windows 10, this buffer was always set to 10 ms. +1. Starting with Windows 10, the buffer size is defined by the audio driver (more details below). -6. The Audio Engine reads the data from the buffer and processes them. It also loads audio effects in the form of Audio Processing Objects (APOs). -7. The latency of the APOs varies based on the signal processing within the APOs. -8. Before Windows 10, the latency of the Audio Engine was equal to ~6ms for applications that use floating point data and ~0ms for applications that use integer data. -9. In Windows 10, the latency has been reduced to ~0ms for all applications. +1. The audio engine reads the data from the buffer and processes them. It also loads audio effects in the form of audio processing objects (APOs). +1. The latency of the APOs varies based on the signal processing within the APOs. +1. Before Windows 10, the latency of the audio engine was equal to ~6 ms for applications that use floating point data and ~0ms for applications that use integer data. +1. In Windows 10 and later, the latency has been reduced to ~0ms for all applications. -10. The application is signaled that data is available to be read, as soon as the audio engine finishes with its processing. - The audio stack also provides the option of Exclusive Mode. In that case, the data bypasses the Audio Engine and goes directly from the application to the buffer where the driver reads it from. However, if an application opens an endpoint in Exclusive Mode, then there is no other application that can use that endpoint to render or capture audio. +1. The application is signaled that data is available to be read, as soon as the audio engine finishes with its processing. + The audio stack also provides the option of exclusive mode. In that case, the data bypasses the audio engine and goes directly from the application to the buffer where the driver reads it from. However, if an application opens an endpoint in exclusive mode, then there's no other application that can use that endpoint to render or capture audio. -Another popular alternative for applications that need low latency is to use the ASIO (Audio Stream Input/Output) model, which utilizes exclusive mode. After a user installs a 3rd party ASIO driver, applications can send data directly from the application to the ASIO driver. However, the application has to be written in such a way that it talks directly to the ASIO driver. +Another popular alternative for applications that need low latency is to use the ASIO (Audio Stream Input/Output) model, which utilizes exclusive mode. After a user installs a third-party ASIO driver, applications can send data directly from the application to the ASIO driver. However, the application has to be written in such a way that it talks directly to the ASIO driver. -Both alternatives (exclusive mode and ASIO) have their own limitations. They provide low latency, but they have their own limitations (some of which were described above). As a result, Audio Engine has been modified, in order to lower the latency, while retaining the flexibility. +Both alternatives (exclusive mode and ASIO) have their own limitations. They provide low latency, but they have their own limitations (some of which were described above). As a result, the audio engine has been modified, in order to lower the latency, while retaining the flexibility. -## Audio Stack Improvements in Windows 10 +## Audio stack improvements -Windows 10 has been enhanced in three areas to reduce latency: +Windows 10 and later have been enhanced in three areas to reduce latency: -1. All applications that use audio will see a 4.5-16ms reduction in round-trip latency (as was explained in the section above) without any code changes or driver updates, compared to Windows 8.1. - a. Applications that use floating point data will have 16ms lower latency. - b. Applications that use integer data will have 4.5ms lower latency. -2. Systems with updated drivers will provide even lower round-trip latency: - a. Drivers can use new DDIs to report the supported sizes of the buffer that is used to transfer data between the OS and the H/W. This means that data transfers do not have to always use 10ms buffers (as they did in previous OS versions). Instead, the driver can specify if it can use small buffers, e.g. 5ms, 3ms, 1ms, etc. - b. Applications that require low latency can use new audio APIs (AudioGraph or WASAPI), in order to query the buffer sizes that are supported by the driver and select the one that will be used for the data transfer to/from the H/W. -3. When an application uses buffer sizes below a certain threshold to render and capture audio, the OS enters a special mode, where it manages its resources in a way that avoids interference between the audio streaming and other subsystems. This will reduce the interruptions in the execution of the audio subsystem and minimize the probability of audio glitches. When the application stops streaming, the OS returns to its normal execution mode. The audio subsystem consists of the following resources: - a. The audio engine thread that is processing low latency audio. - b. All the threads and interrupts that have been registered by the driver (using the new DDIs that are described in the section about driver resource registration). - c. Some or all of the audio threads from the applications that request small buffers, as well as from all applications that share the same audio device graph (e.g. same signal processing mode) with any application that requested small buffers: -4. AudioGraph callbacks on the streaming path. -5. If the application uses WASAPI, then only the work items that were submitted to the [Real-Time Work Queue API](/windows/desktop/ProcThread/platform-work-queue-api) or [**MFCreateMFByteStreamOnStreamEx**](/windows/win32/api/mfidl/nf-mfidl-mfcreatemfbytestreamonstreamex) and were tagged as "Audio" or "ProAudio". +1. All applications that use audio will see a 4.5-16 ms reduction in round-trip latency (as was explained in the section above) without any code changes or driver updates, compared to Windows 8.1. + 1. Applications that use floating point data will have 16-ms lower latency. + 1. Applications that use integer data will have 4.5-ms lower latency. +1. Systems with updated drivers will provide even lower round-trip latency: + 1. Drivers can use new DDIs to report the supported sizes of the buffer that is used to transfer data between Windows and the hardware. Data transfers don't have to always use 10-ms buffers, as they did in previous Windows versions. Instead, the driver can specify if it can use small buffers, for example, 5 ms, 3 ms, 1 ms, etc. + 1. Applications that require low latency can use new audio APIs (AudioGraph or WASAPI), to query the buffer sizes that are supported by the driver and select the one that will be used for the data transfer to/from the hardware. +1. When an application uses buffer sizes below a certain threshold to render and capture audio, Windows enters a special mode, where it manages its resources in a way that avoids interference between the audio streaming and other subsystems. This will reduce the interruptions in the execution of the audio subsystem and minimize the probability of audio glitches. When the application stops streaming, Windows returns to its normal execution mode. The audio subsystem consists of the following resources: + 1. The audio engine thread that is processing low latency audio. + 1. All the threads and interrupts that have been registered by the driver (using the new DDIs that are described in the section about driver resource registration). + 1. Some or all of the audio threads from the applications that request small buffers, and from all applications that share the same audio device graph (for example, same signal processing mode) with any application that requested small buffers: +1. AudioGraph callbacks on the streaming path. +1. If the application uses WASAPI, then only the work items that were submitted to the [Real-Time Work Queue API](/windows/desktop/ProcThread/platform-work-queue-api) or **[MFCreateMFByteStreamOnStreamEx](/windows/win32/api/mfidl/nf-mfidl-mfcreatemfbytestreamonstreamex)** and were tagged as "Audio" or "ProAudio". -## API Improvements +## API improvements The following two Windows 10 APIs provide low latency capabilities: -- [**AudioGraph**](/uwp/api/Windows.Media.Audio.AudioGraph) +- **[AudioGraph](/uwp/api/Windows.Media.Audio.AudioGraph)** - [Windows Audio Session API (WASAPI)](/windows/desktop/CoreAudio/wasapi) -This is how an application developer can determine which of the two APIs to use: +To determine which of the two APIs to use: - Favor AudioGraph, wherever possible for new application development. - Only use WASAPI, if: - - You need additional control than that provided by AudioGraph. + - You need more control than that provided by AudioGraph. - You need lower latency than that provided by AudioGraph. -The [measurement tools](#measurement-tools) section of this topic, shows specific measurements from a Haswell system using the inbox HDAudio driver. +The [measurement tools](#measurement-tools) section of this article, shows specific measurements from a Haswell system using the inbox HDAudio driver. The following sections will explain the low latency capabilities in each API. As it was noted in the previous section, in order for the system to achieve the minimum latency, it needs to have updated drivers that support small buffer sizes. ### AudioGraph -AudioGraph is a new Universal Windows Platform API in Windows 10 that is aimed at realizing interactive and music creation scenarios with ease. AudioGraph is available in several programming languages (C++, C#, JavaScript) and has a simple and feature-rich programming model. +AudioGraph is a new Universal Windows Platform API in Windows 10 and later that is aimed at realizing interactive and music creation scenarios with ease. AudioGraph is available in several programming languages (C++, C#, JavaScript) and has a simple and feature-rich programming model. -In order to target low latency scenarios, AudioGraph provides the [AudioGraphSettings::QuantumSizeSelectionMode property](/uwp/api/Windows.Media.Audio.AudioGraphSettings#Windows_Media_Audio_AudioGraphSettings_QuantumSizeSelectionMode). This property can any of the following values shown in the table below: +In order to target low latency scenarios, AudioGraph provides the **[AudioGraphSettings::QuantumSizeSelectionMode](/uwp/api/Windows.Media.Audio.AudioGraphSettings#Windows_Media_Audio_AudioGraphSettings_QuantumSizeSelectionMode)** property. This property can be any of the values shown in the table below: -|Value|Description| -|--- |--- | -|SystemDefault|Sets the buffer to the default buffer size (~10ms)| -|LowestLatency|Sets the buffer to the minimum value that is supported by the driver| -|ClosestToDesired|Sets the buffer size to be either equal either to the value defined by the DesiredSamplesPerQuantum property or to a value that is as close to DesiredSamplesPerQuantum as is supported by the driver.| +| Value | Description | +|---|---| +| SystemDefault | Sets the buffer to the default buffer size (~10 ms) | +| LowestLatency | Sets the buffer to the minimum value that is supported by the driver | +| ClosestToDesired | Sets the buffer size to be either equal either to the value defined by the DesiredSamplesPerQuantum property or to a value that is as close to DesiredSamplesPerQuantum as is supported by the driver. | - The AudioCreation sample (available for download on GitHub: ) shows how to use AudioGraph for low latency. The following code snippet shows how to set the minimum buffer size: +The [AudioCreation sample](https://github.com/Microsoft/Windows-universal-samples/tree/master/Samples/AudioCreation) shows how to use AudioGraph for low latency. The following code snippet shows how to set the minimum buffer size: ```csharp AudioGraphSettings settings = new AudioGraphSettings(AudioRenderCategory.Media); @@ -134,27 +134,27 @@ settings.QuantumSizeSelectionMode = QuantumSizeSelectionMode.LowestLatency; CreateAudioGraphResult result = await AudioGraph.CreateAsync(settings); ``` -### Windows Audio Session API (WASAPI) +### Windows audio session API (WASAPI) -Starting in Windows 10 , WASAPI has been enhanced to: +Starting in Windows 10, WASAPI has been enhanced to: -- Allow an application to discover the range of buffer sizes (i.e. periodicity values) that are supported by the audio driver of a given audio device. This makes it possible for an application to choose between the default buffer size (10ms) or a small buffer (<10ms) when opening a stream in shared mode. If an application does not specify a buffer size, then it will use the default buffer size. +- Allow an application to discover the range of buffer sizes (that is, periodicity values) that are supported by the audio driver of a given audio device. This makes it possible for an application to choose between the default buffer size (10 ms) or a small buffer (less than 10 ms) when opening a stream in shared mode. If an application doesn't specify a buffer size, then it will use the default buffer size. - Allow an application to discover the current format and periodicity of the audio engine. This allows applications to snap to the current settings of the audio engine. -- Allow an app to specify that it wishes to render/capture in the format it specifies without any re-sampling by the audio engine +- Allow an app to specify that it wishes to render/capture in the format it specifies without any resampling by the audio engine The above features will be available on all Windows devices. However, certain devices with enough resources and updated drivers will provide a better user experience than others. -The above functionality is provided by a new interface, called [**IAudioClient3**](/windows/win32/api/audioclient/nn-audioclient-iaudioclient3), which derives from [**IAudioClient2**](/windows/win32/api/audioclient/nn-audioclient-iaudioclient2). +The above functionality is provided by a new interface, called **[IAudioClient3](/windows/win32/api/audioclient/nn-audioclient-iaudioclient3)**, which derives from **[IAudioClient2](/windows/win32/api/audioclient/nn-audioclient-iaudioclient2)**. -[**IAudioClient3**](/windows/win32/api/audioclient/nn-audioclient-iaudioclient3) defines the following 3 methods: +**[IAudioClient3](/windows/win32/api/audioclient/nn-audioclient-iaudioclient3)** defines the following 3 methods: -|Method|Description| -|--- |--- | -|GetCurrentSharedModeEnginePeriod|Returns the current format and periodicity of the audio engine| -|GetSharedModeEnginePeriod|Returns the range of periodicities supported by the engine for the specified stream format| -|InitializeSharedAudioStream|Initializes a shared stream with the specified periodicity| +| Method | Description | +|---|---| +| GetCurrentSharedModeEnginePeriod | Returns the current format and periodicity of the audio engine | +| GetSharedModeEnginePeriod | Returns the range of periodicities supported by the engine for the specified stream format | +| InitializeSharedAudioStream | Initializes a shared stream with the specified periodicity | -The WASAPIAudio sample (available on GitHub: ) shows how to use IAudioClient3 for low latency. +The [WASAPIAudio sample](https://github.com/Microsoft/Windows-universal-samples/tree/master/Samples/WindowsAudioSession) shows how to use IAudioClient3 for low latency. The following code snippet shows how a music creation app can operate in the lowest latency setting that is supported by the system. @@ -239,7 +239,7 @@ if (AUDCLNT_E_ENGINE_FORMAT_LOCKED == hr) { } ``` -Also, it is recommended for applications that use WASAPI to also use the [Real-Time Work Queue API](/windows/desktop/ProcThread/platform-work-queue-api) or the [**MFCreateMFByteStreamOnStreamEx**](/windows/win32/api/mfidl/nf-mfidl-mfcreatemfbytestreamonstreamex) to create work items and tag them as Audio or Pro Audio, instead of their own threads. This will allow the OS to manage them in a way that will avoid interference non-audio subsystems. In contrast, all AudioGraph threads are automatically managed correctly by the OS. The following code snippet from the WASAPIAudio sample shows how to use the MF Work Queue APIs. +Also, Microsoft recommends for applications that use WASAPI to also use the [Real-Time Work Queue API](/windows/desktop/ProcThread/platform-work-queue-api) or the **[MFCreateMFByteStreamOnStreamEx](/windows/win32/api/mfidl/nf-mfidl-mfcreatemfbytestreamonstreamex)** to create work items and tag them as Audio or Pro Audio, instead of their own threads. This will allow Windows to manage them in a way that will avoid interference non-audio subsystems. In contrast, all AudioGraph threads are automatically managed correctly by Windows. The following code snippet from the WASAPIAudio sample shows how to use the MF Work Queue APIs. ```cpp // Specify Source Reader Attributes @@ -388,30 +388,30 @@ Exit: } ``` -Finally, application developers that use WASAPI need to tag their streams with the audio category and whether to use the raw signal processing mode, based on the functionality of each stream. It is recommended that all audio streams do not use the raw signal processing mode, unless the implications are understood. Raw mode bypasses all the signal processing that has been chosen by the OEM, so: +Finally, application developers that use WASAPI need to tag their streams with the audio category and whether to use the raw signal processing mode, based on the functionality of each stream. Microsoft recommends that all audio streams not use the raw signal processing mode, unless the implications are understood. Raw mode bypasses all the signal processing that has been chosen by the OEM, so: -- The render signal for a particular endpoint might be sub-optimal. -- The capture signal might come in a format that the application cannot understand. +- The render signal for a particular endpoint might be suboptimal. +- The capture signal might come in a format that the application can't understand. - The latency might be improved. -## Driver Improvements +## Driver improvements -In order for audio drivers to support low latency, Windows 10 provides the following 3 new features: +In order for audio drivers to support low latency, Windows 10 and later provide the following features: 1. \[Mandatory\] Declare the minimum buffer size that is supported in each mode. -2. \[Optional, but recommended\] Improve the coordination for the data flow between the driver and the OS. -3. \[Optional, but recommended\] Register the driver resources (interrupts, threads), so that they can be protected by the OS in low latency scenarios. -HDAudio miniport function drivers that are enumerated by the inbox HDAudio bus driver hdaudbus.sys do not need to register the HDAudio interrupts, as this is already done by hdaudbus.sys. However, if the miniport driver creates its own threads, then it needs to register them. +1. \[Optional, but recommended\] Improve the coordination for the data flow between the driver and Windows. +1. \[Optional, but recommended\] Register the driver resources (interrupts, threads), so that they can be protected by Windows in low latency scenarios. +HDAudio miniport function drivers that are enumerated by the inbox HDAudio bus driver hdaudbus.sys don't need to register the HDAudio interrupts, as this is already done by hdaudbus.sys. However, if the miniport driver creates its own threads, then it needs to register them. The following three sections will explain each new feature in more depth. ### Declare the minimum buffer size -A driver operates under various constraints when moving audio data between the OS, the driver, and the hardware. These constraints may be due to the physical hardware transport that moves data between memory and hardware, and/or due to the signal processing modules within the hardware or associated DSP. +A driver operates under various constraints when moving audio data between Windows, the driver, and the hardware. These constraints may be due to the physical hardware transport that moves data between memory and hardware, or due to the signal processing modules within the hardware or associated DSP. -Beginning in Windows 10, version 1607, the driver can express its buffer size capabilities using the DEVPKEY\_KsAudio\_PacketSize\_Constraints2 device property. This property allows the user to define the absolute minimum buffer size that is supported by the driver, as well as specific buffer size constraints for each signal processing mode (the mode-specific constraints need to be higher than the drivers minimum buffer size, otherwise they are ignored by the audio stack). +Beginning in Windows 10, version 1607, the driver can express its buffer size capabilities using the DEVPKEY_KsAudio_PacketSize_Constraints2 device property. This property allows the user to define the absolute minimum buffer size that is supported by the driver, and specific buffer size constraints for each signal processing mode. The mode-specific constraints need to be higher than the drivers minimum buffer size, otherwise they're ignored by the audio stack. -For example, the following code snippet shows how a driver can declare that the absolute minimum supported buffer size is 2 ms, but default mode supports 128 frames (which corresponds to 3 ms, if we assume 48 kHz sample rate). +For example, the following code snippet shows how a driver can declare that the absolute minimum supported buffer size is 2 ms, but default mode supports 128 frames, which corresponds to 3 ms if we assume a 48-kHz sample rate. ```cpp @@ -445,74 +445,74 @@ static struct }; ``` -See the following topics for more in-depth information regarding these structures: +See the following articles for more in-depth information regarding these structures: -- [**KSAUDIO\_PACKETSIZE\_CONSTRAINTS structure**](/windows-hardware/drivers/ddi/ksmedia/ns-ksmedia-_ksaudio_packetsize_constraints) -- [**KSAUDIO\_PACKETSIZE\_CONSTRAINTS2 structure**](/windows-hardware/drivers/ddi/ksmedia/ns-ksmedia-_ksaudio_packetsize_constraints2) - - [**KSAUDIO\_PACKETSIZE\_PROCESSINGMODE\_CONSTRAINT structure**](/windows-hardware/drivers/ddi/ksmedia/ns-ksmedia-_ksaudio_packetsize_signalprocessingmode_constraint) +- **[KSAUDIO_PACKETSIZE_CONSTRAINTS structure](/windows-hardware/drivers/ddi/ksmedia/ns-ksmedia-_ksaudio_packetsize_constraints)** +- **[KSAUDIO_PACKETSIZE_CONSTRAINTS2 structure](/windows-hardware/drivers/ddi/ksmedia/ns-ksmedia-_ksaudio_packetsize_constraints2)** +- **[KSAUDIO_PACKETSIZE_PROCESSINGMODE_CONSTRAINT structure](/windows-hardware/drivers/ddi/ksmedia/ns-ksmedia-_ksaudio_packetsize_signalprocessingmode_constraint)** -Also, the sysvad sample () shows how to use these properties, in order for a driver to declare the minimum buffer for each mode. +Also, the [sysvad sample](https://github.com/Microsoft/Windows-driver-samples/tree/main/audio/sysvad) shows how to use these properties, in order for a driver to declare the minimum buffer for each mode. ### Improve the coordination between driver and OS The DDIs that are described in this section allow the driver to: -- Clearly indicate which half (packet) of the buffer is available to the OS, rather than the OS guessing based on a codec link position. This helps the OS to recover from audio glitches faster. +- Clearly indicate which half (packet) of the buffer is available to Windows, rather than the OS guessing based on a codec link position. This helps Windows to recover from audio glitches faster. - Optionally optimize or simplify its data transfers in and out of the WaveRT buffer. The amount of benefit here depends on DMA engine design or other data transfer mechanism between the WaveRT buffer and (possibly DSP) hardware. - "Burst" captured data faster than real-time if the driver has internally accumulated captured data. This is primarily intended for voice activation scenarios but can apply during normal streaming as well. -- Provide timestamp information about its current stream position rather than the OS guessing, potentially allowing for extremely accurate position information. +- Provide timestamp information about its current stream position rather than Windows guessing, potentially allowing for accurate position information. -This DDI is very useful in the case, where an DSP is used. However, a standard HD Audio driver or other simple circular DMA buffer designs might not find much benefit in these new DDIs listed here. +This DDI is useful in the case, where a DSP is used. However, a standard HD Audio driver or other simple circular DMA buffer designs might not find much benefit in these new DDIs listed here. - [IMiniportWaveRTInputStream](/windows-hardware/drivers/ddi/portcls/nn-portcls-iminiportwavertinputstream) - [IMiniportWaveRTOutputStream](/windows-hardware/drivers/ddi/portcls/nn-portcls-iminiportwavertoutputstream) Several of the driver routines return Windows performance counter timestamps reflecting the time at which samples are captured or presented by the device. -In devices that have complex DSP pipelines and signal processing, calculating an accurate timestamp may be challenging and should be done thoughtfully. The timestamps should not simply reflect the time at which samples were transferred to or from the OS to the DSP. +In devices that have complex DSP pipelines and signal processing, calculating an accurate timestamp may be challenging and should be done thoughtfully. The timestamps shouldn't reflect the time at which samples were transferred to or from Windows to the DSP. To calculate the performance counter values, the driver and DSP might employ some of the following methods. - Within the DSP, track sample timestamps using some internal DSP wall clock. -- Between the driver and DSP, calculate a correlation between the Windows performance counter and the DSP wall clock. Procedures for this can range from very simple (but less precise) to fairly complex or novel (but more precise). +- Between the driver and DSP, calculate a correlation between the Windows performance counter and the DSP wall clock. Procedures for this can range from simple (but less precise) to fairly complex or novel (but more precise). - Factor in any constant delays due to signal processing algorithms or pipeline or hardware transports, unless these delays are otherwise accounted for. -The sysvad sample () shows how to use the above DDIs. +The [sysvad sample](https://github.com/Microsoft/Windows-driver-samples/tree/main/audio/sysvad) shows how to use the above DDIs. -### Register the driver resources +### Register driver resources -To help ensure glitch-free operation, audio drivers must register their streaming resources with portcls. This allows the OS to manage resources to avoid interference between audio streaming and other subystems. +To help ensure glitch-free operation, audio drivers must register their streaming resources with Portcls. This allows Windows to manage resources to avoid interference between audio streaming and other subsystems. -Stream resources are any resources used by the audio driver to process audio streams or ensure audio data flow. At this time, only two type of stream resources are supported: interrupts and driver-owned threads. Audio drivers should register a resource after creating the resource, and unregister the resource before deleted it. +Stream resources are any resources used by the audio driver to process audio streams or ensure audio data flow. Only two types of stream resources are supported: interrupts and driver-owned threads. Audio drivers should register a resource after creating the resource, and unregister the resource before deleted it. -Audio drivers can register resources at initialization time when the driver is loaded, or at run-time, for example when there is an I/O resource rebalance. Portcls uses a global state to keep track of all the audio streaming resources. +Audio drivers can register resources at initialization time when the driver is loaded, or at run-time, for example when there's an I/O resource rebalance. Portcls uses a global state to keep track of all the audio streaming resources. -In some use cases, such as those requiring very low latency audio, the OS attempts to isolate the audio driver's registered resources from interference from other OS, application, and hardware activity. The OS and audio subsystem do this as-needed without interacting with the audio driver, except for the audio driver's registration of the resources. +In some use cases, such as those requiring very low latency audio, Windows attempts to isolate the audio driver's registered resources from interference from other OS, application, and hardware activity. The OS and audio subsystem do this as-needed without interacting with the audio driver, except for the audio driver's registration of the resources. This requirement to register stream resources implies that all drivers that are in the streaming pipeline path must register their resources directly or indirectly with Portcls. The audio miniport driver has these options: - The audio miniport driver is the bottom driver of its stack (interfacing the h/w directly), in this case, the driver knows its stream resources and it can register them with Portcls. - The audio miniport driver is streaming audio with the help of other drivers (example audio bus drivers). These other drivers also use resources that must be registered with Portcls. These parallel/bus driver stacks can expose a public (or private interface, if a single vendor owns all the drivers) that audio miniport drivers use to collect this info. -- The audio miniport driver is streaming audio with the help of other drivers (example hdaudbus). These other drivers also use resources that must be registered with Portcls. These parallel/bus drivers can link with Portcls and directly register their resources. Note that the audio miniport drivers must let Portcls know that they depend on the resources of these other parallel/bus devices (PDOs). The hd-audio infrastructure uses this option, i.e., the hd-audio-bus driver links with Portcls and automatically performs the following steps: +- The audio miniport driver is streaming audio with the help of other drivers (example hdaudbus). These other drivers also use resources that must be registered with Portcls. These parallel/bus drivers can link with Portcls and directly register their resources. The audio miniport drivers must let Portcls know that they depend on the resources of these other parallel/bus devices (PDOs). The HD audio infrastructure uses this option, that is, the HD audio-bus driver links with Portcls and automatically performs the following steps: - registers its bus driver's resources, and - notifies Portcls that the children's resources depend on the parent's resources. In the HD audio architecture, the audio miniport driver just needs to register its own driver-owned thread resources. Notes: -- HDAudio miniport function drivers that are enumerated by the inbox HDAudio bus driver hdaudbus.sys do not need to register the HDAudio interrupts, as this is already done by hdaudbus.sys. However, if the miniport driver creates its own threads, then it needs to register them. -- Drivers that link with Portcls only for the purpose of registering streaming resources must update their INFs to include/needs wdmaudio.inf and copy portcls.sys (and dependent files). A new INF copy section is defined in wdmaudio.inf to only copy those files. -- Audio drivers that only run in Windows 10 can hard-link to: - - [**PcAddStreamResource**](/windows-hardware/drivers/ddi/portcls/nf-portcls-pcaddstreamresource) - - [**PcRemoveStreamResource**](/windows-hardware/drivers/ddi/portcls/nf-portcls-pcremovestreamresource) -- Audio drivers that must run on a down-level OS can use the following interface (the miniport can call QueryInterface for the IID\_IPortClsStreamResourceManager interface and register its resources only when PortCls supports the interface). +- HDAudio miniport function drivers that are enumerated by the inbox HDAudio bus driver hdaudbus.sys don't need to register the HDAudio interrupts, as this is already done by hdaudbus.sys. However, if the miniport driver creates its own threads, then it needs to register them. +- Drivers that link with Portcls only for registering streaming resources must update their INFs to include wdmaudio.inf and copy portcls.sys (and dependent files). A new INF copy section is defined in wdmaudio.inf to only copy those files. +- Audio drivers that only run in Windows 10 and later can hard-link to: + - **[PcAddStreamResource](/windows-hardware/drivers/ddi/portcls/nf-portcls-pcaddstreamresource)** + - **[PcRemoveStreamResource](/windows-hardware/drivers/ddi/portcls/nf-portcls-pcremovestreamresource)** +- Audio drivers that must run on a down-level OS can use the following interface (the miniport can call QueryInterface for the IID_IPortClsStreamResourceManager interface and register its resources only when PortCls supports the interface). - [IPortClsStreamResourceManager](/windows-hardware/drivers/ddi/portcls/nn-portcls-iportclsstreamresourcemanager) - - [**AddStreamResource**](/windows-hardware/drivers/ddi/portcls/nf-portcls-iportclsstreamresourcemanager-addstreamresource) - - [**RemoveStreamResource**](/windows-hardware/drivers/ddi/portcls/nf-portcls-iportclsstreamresourcemanager-removestreamresource) + - **[AddStreamResource](/windows-hardware/drivers/ddi/portcls/nf-portcls-iportclsstreamresourcemanager-addstreamresource)** + - **[RemoveStreamResource](/windows-hardware/drivers/ddi/portcls/nf-portcls-iportclsstreamresourcemanager-removestreamresource)** - These DDIs, use this enumeration and structure: - - [**PcStreamResourceType**](/windows-hardware/drivers/ddi/portcls/ne-portcls-_pcstreamresourcetype) - - [**PCSTREAMRESOURCE\_DESCRIPTOR**](/windows-hardware/drivers/ddi/portcls/ns-portcls-_pcstreamresource_descriptor) + - **[PcStreamResourceType](/windows-hardware/drivers/ddi/portcls/ne-portcls-_pcstreamresourcetype)** + - **[PCSTREAMRESOURCE_DESCRIPTOR](/windows-hardware/drivers/ddi/portcls/ns-portcls-_pcstreamresource_descriptor)** -Finally, drivers that link-in PortCls for the sole purpose of registering resources must add the following two lines in their inf's DDInstall section. Audio miniport drivers do not need this because they already have include/needs in wdmaudio.inf. +Finally, drivers that link-in PortCls for the sole purpose of registering resources must add the following two lines in their inf's DDInstall section. Audio miniport drivers don't need this because they already have include/needs in wdmaudio.inf. ```inf [] @@ -522,54 +522,54 @@ Needs=WDMPORTCLS.CopyFilesOnly The above lines make sure that PortCls and its dependent files are installed. -## Measurement Tools +## Measurement tools In order to measure roundtrip latency, user can user utilize tools that play pulses via the speakers and capture them via the microphone. They measure the delay of the following path: 1. The application calls the render API (AudioGraph or WASAPI) to play the pulse -2. The audio is played via the speakers -3. The audio is captured from the microphone -4. The pulse is detected by the capture API (AudioGraph or WASAPI) -In order to measure the roundtrip latency for different buffer sizes, users need to install a driver that supports small buffers. The inbox HDAudio driver has been updated to support buffer sizes between 128 samples (2.66ms@48kHz) and 480 samples (10ms@48kHz). The following steps show how to install the inbox HDAudio driver (which is part of all Windows 10 SKUs): +1. The audio is played via the speakers +1. The audio is captured from the microphone +1. The pulse is detected by the capture API (AudioGraph or WASAPI) +In order to measure the roundtrip latency for different buffer sizes, users need to install a driver that supports small buffers. The inbox HDAudio driver has been updated to support buffer sizes between 128 samples (2.66ms@48kHz) and 480 samples (10ms@48kHz). The following steps show how to install the inbox HDAudio driver (which is part of all Windows 10 and later SKUs): - Start Device Manager. - Under **Sound video and game controllers**, double-click on the device that corresponds to your internal speakers. - In the next window, go to the **Driver** tab. -- Select **Update driver** -> **Browse my computer for driver software** -> **Let me pick from a list of device drivers in this computer** -> **Select High Definition Audio Device** and select **Next**. +- Select **Update driver** -> **Browse my computer for driver software** -> **Let me pick from a list of device drivers in this computer** -> **Select High Definition Audio Device** and select **Next**. - If a window titled "Update driver warning" appears, select **Yes**. - Select **close**. -- If you are asked to reboot the system, select **Yes** to reboot. -- After reboot, the system will be using the inbox Microsoft HDAudio driver and not the 3rd-party codec driver. Remember which driver you were using before, so that you can fallback to that driver, if you want to use the optimal settings for your audio codec. +- If you're asked to reboot the system, select **Yes** to reboot. +- After rebooting, the system will be using the inbox Microsoft HDAudio driver and not the third-party codec driver. Remember which driver you were using before so that you can fall back to that driver if you want to use the optimal settings for your audio codec. -![graph showing the differences in the roundtrip latency between wasapi and audiograph with different buffer sizes.](images/low-latency-audio-roundtrip-latency.png) +:::image type="content" source="images/low-latency-audio-roundtrip-latency.png" alt-text="Graph showing the differences in the roundtrip latency between WASAPI and AudioGraph with different buffer sizes."::: The differences in the latency between WASAPI and AudioGraph are due to the following reasons: -- AudioGraph adds one buffer of latency in the capture side, in order to synchronize render and capture (which is not provided by WASAPI). This addition simplifies the code for applications written using AudioGraph. -- There is an additional buffer of latency in AudioGraph's render side when the system is using > 6ms buffers. -- AudioGraph does not have the option to disable capture audio effects +- AudioGraph adds one buffer of latency in the capture side, in order to synchronize render and capture, which isn't provided by WASAPI. This addition simplifies the code for applications written using AudioGraph. +- There's another buffer of latency in AudioGraph's render side when the system is using greater than 6-ms buffers. +- AudioGraph doesn't have the option to disable capture audio effects. ## Samples -- WASAPI Audio sample: -- AudioCreation sample (AudioGraph): -- Sysvad driver sample: +- [WASAPI audio sample](https://github.com/Microsoft/Windows-universal-samples/tree/master/Samples/WindowsAudioSession) +- [AudioCreation sample (AudioGraph)](https://github.com/Microsoft/Windows-universal-samples/tree/master/Samples/AudioCreation) +- [Sysvad driver sample](https://github.com/Microsoft/Windows-driver-samples/tree/main/audio/sysvad) ## FAQ -**1. Wouldn't it be better, if all applications use the new APIs for low latency? Doesn't low latency always guarantee a better user experience for the user?** +**Wouldn't it be better, if all applications use the new APIs for low latency? Doesn't low latency always guarantee a better user experience?** Not necessarily. Low latency has its tradeoffs: -- Low latency means higher power consumption. If the system uses 10ms buffers, it means that the CPU will wake up every 10ms, fill the data buffer and go to sleep. However, if the system uses 1ms buffers, it means that the CPU will wake up every 1ms. In the second scenario, this means that the CPU will wake up more often and the power consumption will increase. This will decrease battery life. +- Low latency means higher power consumption. If the system uses 10-ms buffers, it means that the CPU will wake up every 10 ms, fill the data buffer and go to sleep. However, if the system uses 1-ms buffers, it means that the CPU will wake up every 1 ms. In the second scenario, this means that the CPU will wake up more often and the power consumption will increase. This will decrease battery life. - Most applications rely on audio effects to provide the best user experience. For example, media players want to provide high-fidelity audio. Communication applications want to minimum echo and noise. Adding these types of audio effects to a stream increases its latency. These applications are more interested in audio quality than in audio latency. -In summary, each application type has different needs regarding audio latency. If an application does not need low latency, then it should not use the new APIs for low latency. +In summary, each application type has different needs regarding audio latency. If an application doesn't need low latency, then it shouldn't use the new APIs for low latency. -**2. Will all systems that update to Windows 10 be automatically update to support small buffers? Also, will all systems support the same minimum buffer size?** +**Will all systems that update to Windows 10 and later be automatically update to support small buffers? Will all systems support the same minimum buffer size?** -No. In order for a system to support small buffers, it needs to have updated drivers. It is up to the OEMs to decide which systems will be updated to support small buffers. Also, newer systems are more likey to support smaller buffers than older systems (i.e. the latency in new systems will most likely be lower than older systems). +No, in order for a system to support small buffers it needs to have updated drivers. It's up to the OEMs to decide which systems will be updated to support small buffers. Also, newer systems are more likely to support smaller buffers than older systems. The latency in new systems will most likely be lower than older systems. -**3. If a driver supports small buffer sizes (<10ms buffers), will all applications in Windows 10 automatically use small buffers to render and capture audio?** +**If a driver supports small buffer sizes, will all applications in Windows 10 and later automatically use small buffers to render and capture audio?** -No. By default, all applications in Windows 10 will use 10ms buffers to render and capture audio. If an application needs to use small buffers, then it needs to use the new AudioGraph settings or the WASAPI IAudioClient3 interface, in order to do so. However, if one application in Windows 10 requests the usage of small buffers, then the Audio Engine will start transferring audio using that particular buffer size. In that case, all applications that use the same endpoint and mode will automatically switch to that small buffer size. When the low latency application exits, the Audio Engine will switch to 10ms buffers again. +No, by default all applications in Windows 10 and later will use 10-ms buffers to render and capture audio. If an application needs to use small buffers, then it needs to use the new AudioGraph settings or the WASAPI IAudioClient3 interface, in order to do so. However, if one application requests the usage of small buffers, then the audio engine will start transferring audio using that particular buffer size. In that case, all applications that use the same endpoint and mode will automatically switch to that small buffer size. When the low latency application exits, the audio engine will switch to 10-ms buffers again. diff --git a/windows-driver-docs-pr/audio/macro-definitions-for-obsolete-functions.md b/windows-driver-docs-pr/audio/macro-definitions-for-obsolete-functions.md index 5f63f99234..bffed72f65 100644 --- a/windows-driver-docs-pr/audio/macro-definitions-for-obsolete-functions.md +++ b/windows-driver-docs-pr/audio/macro-definitions-for-obsolete-functions.md @@ -1,9 +1,11 @@ --- title: Macro Definitions for Obsolete Functions description: Macro Definitions for Obsolete Functions -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # Macro Definitions for Obsolete Functions diff --git a/windows-driver-docs-pr/audio/making-portdmus-the-default-directmusic-port-driver.md b/windows-driver-docs-pr/audio/making-portdmus-the-default-directmusic-port-driver.md index 5167bdb645..2bae242b14 100644 --- a/windows-driver-docs-pr/audio/making-portdmus-the-default-directmusic-port-driver.md +++ b/windows-driver-docs-pr/audio/making-portdmus-the-default-directmusic-port-driver.md @@ -4,7 +4,7 @@ description: Making PortDMus the Default DirectMusic Port Driver keywords: - port drivers WDK audio , default DMus port driver - default DMus port driver -ms.date: 04/20/2017 +ms.date: 09/30/2022 --- # Making PortDMus the Default DirectMusic Port Driver @@ -13,9 +13,11 @@ ms.date: 04/20/2017 ## -To make the DMus port driver the default for all DirectMusic applications, generate a GUID (using uuidgen.exe or guidgen.exe, which are included in the Microsoft Windows SDK) to uniquely identify your synth. Your [**KSPROPERTY\_SYNTH\_CAPS**](/previous-versions/ff537389(v=vs.85)) property handler should copy this GUID into the **Guid** member of the [**SYNTHCAPS**](/windows-hardware/drivers/ddi/dmusprop/ns-dmusprop-_synthcaps) structure. Also, modify your driver's INF file to set up the following registry entry: +To make the DMus port driver the default for all DirectMusic applications, generate a GUID (using uuidgen.exe or guidgen.exe, which are included in the Microsoft Windows SDK) to uniquely identify your synth. Your [**KSPROPERTY\_SYNTH\_CAPS**](/previous-versions/ff537389(v=vs.85)) property handler should copy this GUID into the **Guid** member of the [**SYNTHCAPS**](/windows-hardware/drivers/ddi/dmusprop/ns-dmusprop-_synthcaps) structure. Also, modify your driver's INF file to set up the following registry entry. + + +| Description | Value | +|--------------|--------------------------| +| Key | HKR\DirectMusic\Defaults | +| String Value | DefaultOutputPort | -```inf -Key: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\DirectMusic\Defaults -String Value: DefaultOutputPort -``` diff --git a/windows-driver-docs-pr/audio/management-of-i2s-and-sco-resources.md b/windows-driver-docs-pr/audio/management-of-i2s-and-sco-resources.md deleted file mode 100644 index 6660fc3c20..0000000000 --- a/windows-driver-docs-pr/audio/management-of-i2s-and-sco-resources.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Management of I2S and SCO Resources -description: The Management of I2S and SCO Resources topic discusses the assumptions that were made in the design of this new support for Bluetooth bypass audio streaming in Windows 8.1. -ms.date: 04/20/2017 ---- - -# Management of I2S and SCO Resources - - -The Management of I2S and SCO Resources topic discusses the assumptions that were made in the design of this new support for Bluetooth bypass audio streaming in Windows 8.1. - -At this time Windows assumes that there is only one Bluetooth host controller. And also, the HFP synchronous connection oriented (SCO) bypass support assumes that there is only one bypass connection and that, any channel opened through the HFP device driver interface is associated with that single connection. - -Audio drivers should arbitrate this channel and the single bypass connection for a single consumer on a first-come first-serve basis. The simplest way to achieve this is for the driver to allow only a single filter to transition its pins to the ACQUIRE state. - -## Related topics -[Theory of Operation](theory-of-operation.md) - - - diff --git a/windows-driver-docs-pr/audio/media-class-inf-extensions.md b/windows-driver-docs-pr/audio/media-class-inf-extensions.md index 3023cdaba5..915e66ca55 100644 --- a/windows-driver-docs-pr/audio/media-class-inf-extensions.md +++ b/windows-driver-docs-pr/audio/media-class-inf-extensions.md @@ -1,9 +1,11 @@ --- title: Audio INF File Settings description: Audio INF File Settings -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # Audio INF File Settings diff --git a/windows-driver-docs-pr/audio/mod-message.md b/windows-driver-docs-pr/audio/mod-message.md new file mode 100644 index 0000000000..f700267836 --- /dev/null +++ b/windows-driver-docs-pr/audio/mod-message.md @@ -0,0 +1,174 @@ +--- +title: modMessage function (Windows Drivers) +description: Learn more about the modMessage function. +keywords: +- mmddk/modMessage +- modMessage +ms.date: 03/06/2023 +ms.topic: reference +--- + +# modMessage function + +The **modMessage** function is the entry-point function for musical instrument digital interface (MIDI) output drivers and for internal synthesizer drivers. For more information about audio device messages related to MIDI, see [Audio Device Messages for MIDI](https://msdn.microsoft.com/library/ff536194\(v=vs.85\)). + +## Syntax + +``` c++ +DWORD modMessage( +  UINT      uDeviceID, +  UINT      uMsg, +  DWORD_PTR dwUser, +  DWORD_PTR dwParam1, +  DWORD_PTR dwParam2 +); +``` + +## Parameters + +- *uDeviceID* + Specifies the ID of the target device. Device IDs are sequential and have an initial value of zero and a final value equal to one less than the number of devices the driver supports. + +- *uMsg* + Specifies the message that WINMM sends to the driver in response to a call from the client application. + +- *dwUser* + For the [**MODM\_OPEN**](modm-open.md) message, the driver should fill this location with its instance data. For any other messages, the instance data is returned to the driver. Drivers that support multiple clients can use this instance data to track which client is associated with the message. + +- *dwParam1* + Specifies a message-dependent parameter. + +- *dwParam2* + Specifies a message-dependent parameter. If there are flags that provide additional information to the driver that works with **modMessage**, WINMM uses this parameter to pass the flags. + +## Return value + +The **modMessage** function returns MMSYSERR\_NOERROR if it can successfully process the message it received from MMSYSTEM. Otherwise, it returns one of the following error messages. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Return codeDescription
MMSYSERR_ERROR

Unspecified error.

MMSYSERR_BADDEVICEID

The specified device ID is out of range.

MMSYSERR_NOTENABLED

The driver failed to load or initialize.

MMSYSERR_ALLOCATED

The specified device is already allocated.

MMSYSERR_INVALHANDLE

The handle of the specified device is invalid.

MMSYSERR_NODRIVER

No device driver is present.

MMSYSERR_NOMEM

Memory allocation error.

MMSYSERR_NOTSUPPORTED

The function requested by the message is not supported.

MMSYSERR_BADERRNUM

Error value is out of range. See Remarks section for more details.

MMSYSERR_INVALFLAG

An invalid flag was passed to modMessage(by using dwParam2).

MMSYSERR_INVALPARAM

An invalid parameter was passed to modMessage.

MMSYSERR_HANDLEBUSY

The specified handle is being used simultaneously by another thread (for example, a callback thread).

MMSYSERR_INVALIDALIAS

The specified alias was not found.

MMSYSERR_BADDB

Bad registry database.

MMSYSERR_KEYNOTFOUND

The specified registry key was not found.

MMSYSERR_READERROR

Registry read error.

MMSYSERR_WRITEERROR

Registry write error.

MMSYSERR_DELETEERROR

Registry delete error.

MMSYSERR_VALNOTFOUND

The specified registry value was not found.

MMSYSERR_NODRIVERCB

The driver that works with modMessage does not call DriverCallback.

MMSYSERR_MOREDATA

modMessage has more data to return.

MMSYSERR_LASTERROR

Indicates that this is the last error in the range of error values. See the Remarks section for more details.

+ +## Remarks + +Audio device messages are system-defined constants. So when **modMessage** receives an audio device message, it uses a switch statement to determine the action to perform, based on the value of the message. + +The range of error messages that **modMessage** can return depends on the message that it was processing when the error occurred. The numerical values of the MMSYSERR\_ error messages start with zero (for MMSYSERR\_NOERROR) and continue with MMSYSERR\_BASE + *n*, where *n* is an integer from 1 to 21. The value for MMSYSERR\_BASE is a defined constant. For more information about MSYSERR\_BASE and the MMSYSERR\_ error messages, see Mmsystem.h in the Windows SDK and Mmddk.h in the WDK respectively. + +## Requirements + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Available with Windows XP and later Windows operating systems.

Header

Mmddk.h (include Mmddk.h, Mmsystem.h, or Windows.h)
+ +## See also + +[**MODM\_OPEN**](modm-open.md) diff --git a/windows-driver-docs-pr/audio/modified-inf-for-msvad-micarray.md b/windows-driver-docs-pr/audio/modified-inf-for-msvad-micarray.md index 52f75625e1..2ef596d2c8 100644 --- a/windows-driver-docs-pr/audio/modified-inf-for-msvad-micarray.md +++ b/windows-driver-docs-pr/audio/modified-inf-for-msvad-micarray.md @@ -1,12 +1,11 @@ --- title: Modified INF for MSVAD Micarray description: Modified INF for MSVAD Micarray -ms.date: 04/20/2017 +ms.date: 05/05/2023 --- # Modified INF for MSVAD Micarray - This topic shows how to modify the Micarray.inf sample file to provide setup information about how to install the sample microphone array described in [Microphone Array Geometry Property](microphone-array-geometry-property.md). Navigate to Src\\Audio\\Msvad to locate Micarray.inf. Make a copy of the original file under a new name, and then edit Micarray.inf as follows: @@ -14,12 +13,13 @@ Navigate to Src\\Audio\\Msvad to locate Micarray.inf. Make a copy of the origina ```inf // Modified micarray.inf file tailored for a microphone array [Version] -Signature="$CHICAGO$" +Signature="$Windows NT$" Class=MEDIA Provider=%MSFT% ClassGUID={4d36e96c-e325-11ce-bfc1-08002be10318} DriverVer = 02/22/2007, 6.0.6000.1 CatalogFile=msvad.cat +PnpLockdown=1 [SourceDisksNames] 222="MSVAD Driver Disk","",222 @@ -137,25 +137,12 @@ MSVAD_MIDI="MSVAD -> WDM Midi Device" Proxy.CLSID="{17CCA71B-ECD7-11D0-B908-00A0C9223196}" KSCATEGORY_AUDIO="{6994AD04-93EF-11D0-A3CC-00A0C9223196}" -KSCATEGORY_RENDER="{65E8773E-8F56-11D0-A3B9-00A0C9223196}" KSCATEGORY_CAPTURE="{65E8773D-8F56-11D0-A3B9-00A0C9223196}" KSNAME_Wave="Wave" KSNAME_Topology="Topology" msvad_micarray.SvcDesc="Sample Virtual Audio Device (Mic Array) (WDM)" - -MediaCategories="SYSTEM\CurrentControlSet\Control\MediaCategories" -Simple.NameGuid="{946A7B1A-EBBC-422a-A81F-F07C8D40D3B4}" -Simple.Name="MSVAD (Simple)" ``` After you modify the file as shown in the preceding example, save it in its original location. For more information about how to build the microphone array sample driver, see [Microphone Array Geometry Property](microphone-array-geometry-property.md). - - - - - - - - diff --git a/windows-driver-docs-pr/audio/modm-cachedrumpatches.md b/windows-driver-docs-pr/audio/modm-cachedrumpatches.md new file mode 100644 index 0000000000..f8a4f9fbf0 --- /dev/null +++ b/windows-driver-docs-pr/audio/modm-cachedrumpatches.md @@ -0,0 +1,106 @@ +--- +title: MODM_CACHEDRUMPATCHES function (Windows Drivers) +description: Learn more about the MODM_CACHEDRUMPATCHES function. +keywords: +- mmddk/modMessage +- modMessage +ms.date: 03/06/2023 +ms.topic: reference +--- + +# MODM\_CACHEDRUMPATCHES function + +WINMM sends the `MODM_CACHEDRUMPATCHES` message to the [**modMessage**](mod-message.md) function of a MIDI output driver to ask the driver to cache or uncache the specified drum keys. This allows the internal synthesizer drivers to load the patches that are needed by the client application. + +## Syntax + +``` c++ +DWORD modMessage( +  UINT      uDeviceID, +  UINT      uMsg, +  DWORD_PTR dwUser, +  DWORD_PTR dwParam1, +  DWORD_PTR dwParam2 +); +``` + +## Parameters + +- *uDeviceID* + Specifies the ID of the target device. Device IDs are sequential with an initial value of zero and a final value equal to one less than the number of devices that the driver supports. + +- *uMsg* + WINMM sets this parameter to **MODM\_CACHEDRUMPATCHES** when it calls **modMessage** to process this message. + +- *dwUser* + Use this parameter to return instance data to the driver. Drivers that support multiple clients can use this instance data to keep track of the client that is associated with the message. + +- *dwParam1* + Specifies a far pointer to a [KEYARRAY](/windows/win32/multimedia/keyarray) array and indicates the patches that must be cached or uncached. + +- *dwParam2* + The high-order word specifies the bank of patches to which the array refers. The low-order word specifies whether the patches must be cached or uncached (when you call **modMessage**) according to one of the following flags: + + **MIDI\_CACHE\_ALL**. All patches specified in the array must be cached. If the synthesizer cannot cache all the patches, it should not cache any. Instead, it must clear the **KEYARRAY** and return MMSYSERR\_NOMEM. + + **MIDI\_CACHE\_BESTFIT**. If the driver can cache all the patches specified in the array, it must do so. Otherwise, it must cache as many as it can and then alter the **KEYARRAY** to reflect what it has actually cached. The driver must return MMSYSERR\_NOMEM. + + **MIDI\_CACHE\_QUERY**. The array of patches in **KEYARRAY** must be read to determine the patches that have already been cached. + + **MIDI\_UNCACHE**. The patches that are specified in **KEYARRAY** must be uncached and the array must be cleared. + +## Return value + +**modMessage** returns **MMSYSERR\_NOERROR** if the `MODM_CACHEDRUMPATCHES` message was successfully processed. Otherwise, it returns one of the following error messages. + + + + + + + + + + + + + + + + + + +
Return codeDescription
MMSYSERR_NOTENABLED

The driver failed to load or initialize.

MMSYSERR_NOTSUPPORTED

The function specified in the call to modMessage is not supported.

+ +## Remarks + +Patch caching is only supported by internal synthesizer device drivers. Drivers for MIDI output ports must return an MMSYSERR\_NOTSUPPORTED error for this message. Support for patch caching is optional for internal synthesizer devices. When a driver receives a [**MODM\_GETDEVCAPS**](modm-getdevcaps.md) message, it must indicate support for patch caching by setting or clearing the MIDICAPS\_CACHE bit in the **dwSupport** field of the [MIDIOUTCAPS](/windows/win32/api/mmeapi/ns-mmeapi-midioutcaps) data structure. + +## Requirements + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Available in Windows XP and later Windows operating systems.

Header

Mmddk.h (include Mmddk.h, Mmsystem.h, or Windows.h)
+ +## See also + +[**modMessage**](mod-message.md) + +[**MODM\_GETDEVCAPS**](modm-getdevcaps.md) + +[MIDIOUTCAPS](/windows/win32/api/mmeapi/ns-mmeapi-midioutcaps) + +[KEYARRAY](/windows/win32/multimedia/keyarray) diff --git a/windows-driver-docs-pr/audio/modm-cachepatches.md b/windows-driver-docs-pr/audio/modm-cachepatches.md new file mode 100644 index 0000000000..d09b163041 --- /dev/null +++ b/windows-driver-docs-pr/audio/modm-cachepatches.md @@ -0,0 +1,106 @@ +--- +title: MODM_CACHEPATCHES function (Windows Drivers) +description: Learn more about the MODM_CACHEPATCHES function. +keywords: +- mmddk/modMessage +- modMessage +ms.date: 03/06/2023 +ms.topic: reference +--- + +# MODM\_CACHEPATCHES function + +WINMM sends the `MODM_CACHEPATCHES` message to the [**modMessage**](mod-message.md) function of a MIDI output driver to request that the driver cache or uncache the specified patches. This allows internal synthesizer drivers to load the patches that are needed by a client application. + +## Syntax + +``` c++ +DWORD modMessage( +  UINT      uDeviceID, +  UINT      uMsg, +  DWORD_PTR dwUser, +  DWORD_PTR dwParam1, +  DWORD_PTR dwParam2 +); +``` + +## Parameters + +- *uDeviceID* + Specifies the ID of the target device. Device IDs are sequential and have an initial value of zero and a final value that is equal to one less than the number of devices that the driver supports. + +- *uMsg* + WINMM sets this parameter to **MODM\_CACHEPATCHES** when it calls **modMessage** to process this message. + +- *dwUser* + Use this parameter to return instance data to the driver. Drivers that support multiple clients can use this instance data to keep track of the client that is associated with the message. + +- *dwParam1* + Specifies a far pointer to a [PATCHARRAY](/windows/win32/multimedia/patcharray) array and indicates the patches that must be cached or un-cached. + +- *dwParam2* + The high-order word specifies the bank of patches to which the array refers. The low-order word specifies whether the patches must be cached or uncached according to one of the following flags: + + **MIDI\_CACHE\_ALL**. All patches specified in the array must be cached. If the synthesizer cannot cache all the patches, it must not cache any. If the synthesizer fails to cache any patches, it must clear the **PATCHARRAY** and return MMSYSERR\_NOMEM. + + **MIDI\_CACHE\_BESTFIT**. If the driver can cache all the patches specified in the array, it must do so. Otherwise, it must cache as many as it can, alter the **PATCHARRAY** to reflect what it has actually cached, and return MMSYSERR\_NOMEM. + + **MIDI\_CACHE\_QUERY**. The **PATCHARRAY** must be read to determine the patches that the driver has actually cached. + + **MIDI\_UNCACHE**. The patches specified in the array must be uncached and the **PATCHARRAY** must be cleared. + +## Return value + +The **modMessage** function returns zero if the operation is successful. Otherwise, it returns one of the error messages in the following table. + + + + + + + + + + + + + + + + + + +
Return codeDescription
MMSYSERR_NOTENABLED

The driver failed to load or initialize.

MMSYSERR_NOTSUPPORTED

The function specified in the call to modMessage is not supported.

+ +## Remarks + +Patch caching is only supported by internal synthesizer drivers. Drivers for MIDI output ports must return an MMSYSERR\_NOTSUPPORTED error in response to the `MODM_CACHEPATCHES` message. Support for patch caching is optional for internal synthesizer devices. When a driver receives a [**MODM\_GETDEVCAPS**](modm-getdevcaps.md) message, it must either set or clear the MIDICAPS\_CACHE bit in the **dwSupport** field of the [MIDIOUTCAPS](/windows/win32/api/mmeapi/ns-mmeapi-midioutcaps) data structure to indicate support for patch caching. + +## Requirements + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Available in Windows XP and later Windows operating systems.

Header

Mmddk.h (include Mmddk.h, Mmsystem.h, or Windows.h)
+ +## See also + +[**modMessage**](mod-message.md) + +[**MODM\_GETDEVCAPS**](modm-getdevcaps.md) + +[MIDIOUTCAPS](/windows/win32/api/mmeapi/ns-mmeapi-midioutcaps) + +[PATCHARRAY](/windows/win32/multimedia/patcharray) diff --git a/windows-driver-docs-pr/audio/modm-data.md b/windows-driver-docs-pr/audio/modm-data.md new file mode 100644 index 0000000000..cf0e5acc1c --- /dev/null +++ b/windows-driver-docs-pr/audio/modm-data.md @@ -0,0 +1,96 @@ +--- +title: MODM_DATA function (Windows Drivers) +description: Learn more about the MODM_DATA function. +keywords: +- mmddk/modMessage +- modMessage +ms.date: 03/06/2023 +ms.topic: reference +--- + +# MODM\_DATA function + +MMSYSTEM sends the `MODM_DATA` message to the [**modMessage**](mod-message.md) function of a MIDI output driver when the client wants to make a single MIDI event available as output. + +## Syntax + +``` c++ +DWORD modMessage( +  UINT      uDeviceID, +  UINT      uMSG, +  DWORD_PTR dwUser, +  DWORD_PTR dwParam1, +  DWORD_PTR dwParam2 +); +``` + +## Parameters + +- *uDeviceID* + Specifies the ID of the target device. Device IDs are sequential and have an initial value of zero and a final value that is equal to one less than the number of devices that the driver supports. + +- *uMSG* + WINMM sets this parameter to **MODM\_DATA** when it calls **modMessage** to process this message. + +- *dwUser* + Use this parameter to return instance data to the driver. Drivers that support multiple clients can use this instance data to track the client that is associated with the message. + +- *dwParam1* + Specifies the MIDI event that will be available at the output. The low-order byte is the first byte of the event. + +- *dwParam2* + Not used. + +## Return value + +If the operation is successful, **modMessage** returns MMSYSERR\_NOERROR. Otherwise, it returns one of the error messages in the following table. + + + + + + + + + + + + + + + + + + +
Return codeDescription
MMSYSERR_NOTENABLED

The driver failed to load or initialize.

MIDIERR_NOTREADY

The MIDI hardware is busy processing other data.

+ +## Remarks + +This message is used to make all MIDI events available as output, except system-exclusive events. System-exclusive events are communicated with the [**MODM\_LONGDATA**](modm-longdata.md) message. MIDI events that are communicated with `MODM_DATA` can be one, two, or three bytes long. The driver must parse the event to determine how many bytes to transfer. Unused bytes are not guaranteed to be zero. + +The driver developer can develop a driver to not return until the message has been sent to the output device. Alternatively, the driver can return immediately and the MIDI data can be output in the background. + +## Requirements + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Available in Windows XP and later Windows operating systems.

Header

Mmddk.h (include Mmddk.h, Mmsystem.h, or Windows.h)
+ +## See also + +[**modMessage**](mod-message.md) + +[**MODM\_LONGDATA**](modm-longdata.md) diff --git a/windows-driver-docs-pr/audio/modm-getdevcaps.md b/windows-driver-docs-pr/audio/modm-getdevcaps.md new file mode 100644 index 0000000000..a17b9799f4 --- /dev/null +++ b/windows-driver-docs-pr/audio/modm-getdevcaps.md @@ -0,0 +1,79 @@ +--- +title: MODM_GETDEVCAPS function (Windows Drivers) +description: Learn more about the MODM_GETDEVCAPS function. +keywords: +- mmddk/modMessage +- modMessage +ms.date: 03/06/2023 +ms.topic: reference +--- + +# MODM\_GETDEVCAPS function + +WINMM sends the `MODM_GETDEVCAPS` message to the [**modMessage**](mod-message.md) function of a MIDI output driver to retrieve information about the capabilities of a specific MIDI output device. + +## Syntax + +``` c++ +DWORD modMessage( +  UINT      uDeviceID, +  UINT      uMsg, +  DWORD_PTR dwUser, +  DWORD_PTR dwParam1, +  DWORD_PTR dwParam2 +); +``` + +## Parameters + +- *uDeviceID* + Specifies the ID of the target device. Device IDs are sequential and have an initial value of zero and a final value that is equal to one less than the number of devices that the driver supports. + +- *uMsg* + WINMM sets this parameter to **MODM\_GETDEVCAPS** when it calls **modMessage** to process this message. + +- *dwUser* + Use this parameter to return instance data to the driver. Drivers that support multiple clients can use this instance data to track the client that is associated with the message. + +- *dwParam1* + For Plug and Play (PnP) drivers, this parameter specifies a pointer to an [**MDEVICECAPSEX**](/windows/win32/api/mmddk/ns-mmddk-mdevicecapsex) structure. The driver fills this structure with the capabilities of the device. + + For drivers that are not Plug and Play, this parameter specifies a far pointer to a [MIDIOUTCAPS](/windows/win32/api/mmeapi/ns-mmeapi-midioutcaps) data structure. The driver fills this structure with the capabilities of the device. + +- *dwParam2* + For Plug and Play drivers, this parameter specifies a device node. For drivers that are not Plug and Play, this parameter specifies the size of the **MIDIOUTCAPS** structure in bytes. + +## Return value + +If the operation is successful, **modMessage** returns MMSYSERR\_NOERROR. Otherwise, it returns MMSYSERR\_NOTENABLED to indicate that the driver failed to load or initialize. + +## Remarks + +For drivers that are not Plug and Play, the driver must only write *dwParam2* or less bytes to the location pointed to by *dwParam1*. + +## Requirements + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Available in Windows XP and later Windows operating systems.

Header

Mmddk.h (include Mmddk.h, Mmsystem.h, or Windows.h)
+ +## See also + +[**modMessage**](mod-message.md) + +[**MDEVICECAPSEX**](/windows/win32/api/mmddk/ns-mmddk-mdevicecapsex) + +[MIDIOUTCAPS](/windows/win32/api/mmeapi/ns-mmeapi-midioutcaps) diff --git a/windows-driver-docs-pr/audio/modm-getnumdevs.md b/windows-driver-docs-pr/audio/modm-getnumdevs.md new file mode 100644 index 0000000000..9c7a6f2202 --- /dev/null +++ b/windows-driver-docs-pr/audio/modm-getnumdevs.md @@ -0,0 +1,73 @@ +--- +title: MODM_GETNUMDEVS function (Windows Drivers) +description: Learn more about the MODM_GETNUMDEVS function. +keywords: +- mmddk/modMessage +- modMessage +ms.date: 03/06/2023 +ms.topic: reference +--- + +# MODM\_GETNUMDEVS function + +WINMM sends the `MODM_GETNUMDEVS` message to the [**modMessage**](mod-message.md) function of a MIDI output driver to request the number of MIDI output devices available. + +## Syntax + +``` c++ +DWORD modMessage( +  UINT      uDeviceID, +  UINT      uMsg, +  DWORD_PTR dwUser, +  DWORD_PTR dwParam1, +  DWORD_PTR dwParam2 +); +``` + +## Parameters + +- *uDeviceID* + Specifies the ID of the target device. Device IDs are sequential and have an initial value of zero and a final value that is equal to one less than the number of devices that the driver supports. + +- *uMsg* + WINMM sets this parameter to **MODM\_GETNUMDEVS** when it calls **modMessage** to process this message. + +- *dwUser* + Use this parameter to return instance data to the driver. Drivers that support multiple clients can use this instance data to keep track of the client that is associated with the message. + +- *dwParam1* + Not used. + +- *dwParam2* + Not used. + +## Return value + +The **modMessage** function returns the number of MIDI output devices that the driver supports. + +## Remarks + +Drivers can be structured in several ways. The simplest and most common drivers use one physical device to support one logical device. Drivers can also support multiple logical devices by using a single physical device. For example, a driver can use a single digital signal processor (DSP) to support two different types of internal synthesizers. Such a driver would return a value of "2" in response to the `MODM_GETNUMDEVS` message. + +## Requirements + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Available in Windows XP and later Windows operating systems.

Header

Mmddk.h (include Mmddk.h, Mmsystem.h, or Windows.h)
+ +## See also + +[**ModMessage**](mod-message.md) diff --git a/windows-driver-docs-pr/audio/modm-getpos.md b/windows-driver-docs-pr/audio/modm-getpos.md new file mode 100644 index 0000000000..6150246e7a --- /dev/null +++ b/windows-driver-docs-pr/audio/modm-getpos.md @@ -0,0 +1,89 @@ +--- +title: MODM_GETPOS function (Windows Drivers) +description: Learn more about the MODM_GETPOS function. +keywords: +- mmddk/modMessage +- modMessage +ms.date: 03/06/2023 +ms.topic: reference +--- + +# MODM\_GETPOS function + +WINMM sends the `MODM_GETPOS` message to the [**modMessage**](mod-message.md) function of a MIDI output driver to request the current position of the stream pointer in the data stream. + +## Syntax + +``` c++ +DWORD modMessage( +  UINT      uDeviceID, +  UINT      uMsg, +  DWORD_PTR dwUser, +  DWORD_PTR dwParam1, +  DWORD_PTR dwParam2 +); +``` + +## Parameters + +- *uDeviceID* + Specifies the ID of the target device. Device IDs are sequential and have an initial value of zero and a final value that is equal to one less than the number of devices that the driver supports. + +- *uMsg* + WINMM sets this parameter to **MODM\_GETPOS** when it calls **modMessage** to process this message. + +- *dwUser* + Use this parameter to return instance data to the driver. Drivers that support multiple clients can use this instance data to track the client that is associated with the message. + +- *dwParam1* + Specifies a far pointer to an [MMTIME](/previous-versions//dd757347(v=vs.85)) structure. + +- *dwParam2* + Specifies the size, in bytes, of the **MMTIME** structure. + +## Return value + +The **modMessage** function returns MMSYSERR\_NOERROR if the operation is successful. Otherwise, it returns MMSYSERR\_NOTENABLED to indicate that the driver failed to load or initialize. + +## Remarks + +The driver should return the position in the time format specified in the **wType** member of **MMTIME**. If the time format specified in **wType** is not supported, the driver must change **wType** to the default time format and return the position in that format. + +Time is measured relative to the start of the first buffer that was sent while the driver was in the last stopped state. The stopped state is entered whenever a [**MODM\_OPEN**](modm-open.md), [**MODM\_RESET**](modm-reset.md), or [**MODM\_STOP**](modm-stop.md) message is received. Time spent between a [**MODM\_PAUSE**](modm-pause.md) and the matching [**MODM\_RESTART**](modm-restart.md) is not counted, but the clock should not be reset. Likewise, the time during which the driver is starved for data must not be counted; the returned time must be as if the stream played perfectly with no interruptions or pauses. + +If the device is paused or starved, the time returned must be the time of the last event played. + +## Requirements + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Available in Windows XP and later Windows operating systems.

Header

Mmddk.h (include Mmddk.h, Mmsystem.h, or Windows.h)
+ +## See also + +[**modMessage**](mod-message.md) + +[MMTIME](/previous-versions//dd757347(v=vs.85)) + +[**MODM\_OPEN**](modm-open.md) + +[**MODM\_RESET**](modm-reset.md) + +[**MODM\_STOP**](modm-stop.md) + +[**MODM\_PAUSE**](modm-pause.md) + +[**MODM\_RESTART**](modm-restart.md) diff --git a/windows-driver-docs-pr/audio/modm-getvolume.md b/windows-driver-docs-pr/audio/modm-getvolume.md new file mode 100644 index 0000000000..56ac0cb9d7 --- /dev/null +++ b/windows-driver-docs-pr/audio/modm-getvolume.md @@ -0,0 +1,94 @@ +--- +title: MODM_GETVOLUME function (Windows Drivers) +description: Learn more about the MODM_GETVOLUME function. +keywords: +- mmddk/modMessage +- modMessage +ms.date: 03/06/2023 +ms.topic: reference +--- + +# MODM\_GETVOLUME function + +WINMM sends the `MODM_GETVOLUME` message to the [**modMessage**](mod-message.md) function of a MIDI output driver to request the current volume level setting for a MIDI device. + +## Syntax + +``` c++ +DWORD modMessage( +  UINT      uDeviceID, +  UINT      uMsg, +  DWORD_PTR dwUser, +  DWORD_PTR dwParam1, +  DWORD_PTR dwParam2 +); +``` + +## Parameters + +- *uDeviceID* + Specifies the ID of the target device. Device IDs are sequential and have an initial value of zero and a final value that is equal to one less than the number of devices that the driver supports. + +- *uMsg* + WINMM sets this parameter to **MODM\_GETVOLUME** when it calls **modMessage** to process this message. + +- *dwUser* + Use this parameter to return instance data to the driver. Drivers that support multiple clients can use this instance data to track the client that is associated with the message. + +- *dwParam1* + This parameter specifies a far pointer to a **DWORD** location. The driver fills this location with the current volume level setting. The high-order word contains the right channel setting and the low-order word contains the left channel setting. A value of zero is silence, and a value of 0xFFFF is full volume. If the driver does not support both left and right channel volume changes, it returns the volume level setting in the low-order word. + +- *dwParam2* + Not used. + +## Return value + +The **modMessage** message returns MMSYSERR\_NOERROR, if the operation is successful. Otherwise, it returns one of the error messages in the following table. + + + + + + + + + + + + + + + + + + +
Return codeDescription
MMSYSERR_NOTENABLED

The driver failed to load or initialize.

MMSYSERR_NOTSUPPORTED

The driver does not support changes to volume level settings.

+ +## Remarks + +Only drivers for internal synthesizer devices can support volume level changes. Drivers for MIDI output ports should return an MMSYSERR\_NOTSUPPORTED error for this message. Support for volume level changes by internal synthesizer devices is optional. However, if a driver supports changes to the volume level with the [**MODM\_SETVOLUME**](modm-setvolume.md) message, it must support queries with the `MODM_GETVOLUME` message. + +## Requirements + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Available in Windows XP and later Windows operating systems.

Header

Mmddk.h (include Mmddk.h, Mmsystem.h, or Windows.h)
+ +## See also + +[**modMessage**](mod-message.md) + +[**MODM\_SETVOLUME**](modm-setvolume.md) diff --git a/windows-driver-docs-pr/audio/modm-longdata.md b/windows-driver-docs-pr/audio/modm-longdata.md new file mode 100644 index 0000000000..4673301412 --- /dev/null +++ b/windows-driver-docs-pr/audio/modm-longdata.md @@ -0,0 +1,108 @@ +--- +title: MODM_LONGDATA function (Windows Drivers) +description: Learn more about the MODM_LONGDATA function. +keywords: +- mmddk/modMessage +- modMessage +ms.date: 03/06/2023 +ms.topic: reference +--- + +# MODM\_LONGDATA function + +WINMM sends the `MODM_LONGDATA` message to the [**modMessage**](mod-message.md) function of a MIDI output driver when a client application wants the driver to make a data block available as output. This data block typically contains one or more MIDI events, including system-exclusive events. If the data block contains more than one MIDI event, the events are packed into the data block with no padding. + +If a client of the MIDI output driver wants to send a single MIDI event, it is more efficient to use the [**MODM\_DATA**](modm-data.md) message. + +## Syntax + +``` c++ +DWORD modMessage( +  UINT      uDeviceID, +  UINT      uMsg, +  DWORD_PTR dwUser, +  DWORD_PTR dwParam1, +  DWORD_PTR dwParam2 +); +``` + +## Parameters + +- *uDeviceID* + Specifies the ID of the target device. Device IDs are sequential and have an initial value of zero and a final value that is equal to one less than the number of devices that the driver supports. + +- *uMsg* + WINMM sets this parameter to **MODM\_LONGDATA** when it calls **modMessage** to process this message. + +- *dwUser* + Use this parameter to return instance data to the driver. Drivers that support multiple clients can use this instance data to track the client that is associated with the message. + +- *dwParam1* + This parameter specifies a far pointer to [MIDIHDR](/windows/win32/api/mmeapi/ns-mmeapi-midihdr) data structure that identifies the data block. + +- *dwParam2* + This parameter specifies the size of the **MIDIHDR** structure. + +## Return value + +The **modMessage** function returns MMSYSERR\_NOERROR if the operation is successful. Otherwise, it returns one of the error messages in the following table. + + + + + + + + + + + + + + + + + + + + + + +
Return codeDescription
MMSYSERR_NOTENABLED

The driver failed to load or initialize.

MIDIERR_UNPREPARED

The specified data block has not been prepared.

MIDIERR_NOTREADY

The MIDI hardware is busy processing other data.

+ +## Remarks + +The driver must first check the MHDR\_PREPARED bit in the **dwFlags** field of the **MIDIHDR** structure. If the bit is not set, the driver must return MIDIERR\_UNPREPARED. The driver must also clear the MHDR\_DONE bit, set the MHDR\_INQUEUE bit, and place the data block in its output queue. Then the driver must return control to the client by returning MMSYSERR\_NOERROR. + +After the data block has been sent as an output, the driver must set the MHDR\_DONE bit and clear the MHDR\_INQUEUE bit before it notifies the client by using [DriverCallback](/windows/win32/api/mmiscapi/nf-mmiscapi-drivercallback) to send a [**MOM\_DONE**](mom-done.md) message. + +The driver developer can design the driver to not return until the message has been sent to the output device. Alternatively, the driver can return immediately, but work in the background to send the MIDI data as output. The driver must maintain MIDI status across multiple [**MODM\_DATA**](modm-data.md) and `MODM_LONGDATA` calls. + +## Requirements + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Available in Windows XP and later Windows operating systems.

Header

Mmddk.h (include Mmddk.h, Mmsystem.h, or Windows.h)
+ +## See also + +[**modMessage**](mod-message.md) + +[MIDIHDR](/windows/win32/api/mmeapi/ns-mmeapi-midihdr) + +[DriverCallback](/windows/win32/api/mmiscapi/nf-mmiscapi-drivercallback) + +[**MOM\_DONE**](mom-done.md) diff --git a/windows-driver-docs-pr/audio/modm-open.md b/windows-driver-docs-pr/audio/modm-open.md new file mode 100644 index 0000000000..ce50bc2549 --- /dev/null +++ b/windows-driver-docs-pr/audio/modm-open.md @@ -0,0 +1,133 @@ +--- +title: MODM_OPEN function (Windows Drivers) +description: Learn more about the MODM_OPEN function. +keywords: +- mmddk/modMessage +- modMessage +ms.date: 03/06/2023 +ms.topic: reference +--- + +# MODM\_OPEN function + +WINMM sends the `MODM_OPEN` message to the [**modMessage**](mod-message.md) function of a MIDI output driver to allocate a specified device that a client application can use. + +## Syntax + +``` c++ +DWORD modMessage( +  UINT      uDeviceID, +  UINT      uMsg, +  DWORD_PTR dwUser, +  DWORD_PTR dwParam1, +  DWORD_PTR dwParam2 +); +``` + +## Parameters + +- *uDeviceID* + Specifies the ID of the target device. Device IDs are sequential and have an initial value of zero and a final value equal that is to one less than the number of devices that the driver supports. + +- *uMsg* + WINMM sets this parameter to **MODM\_OPEN** when it calls **modMessage** to process this message. + +- *dwUser* + The MIDI output driver must fill this location with its instance data, but only in response to the `MODM_OPEN`. + +- *dwParam1* + This parameter specifies a far pointer to a [**MIDIOPENDESC**](/windows/win32/api/mmddk/ns-mmddk-midiopendesc) structure. This structure contains additional information for the driver such as instance data from the client and a callback function for the client. + +- *dwParam2* + This parameter specifies option flags that determine how the device is opened. The flags can be any of the values in the following table. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagMeaning

CALLBACK_EVENT

If this flag is specified, dwCallback in the MIDIOPENDESC structure is assumed to be an event handle.

CALLBACK_FUNCTION

If this flag is specified, dwCallback in the MIDIOPENDESC structure is assumed to be the address of a callback function.

CALLBACK_THREAD

If this flag is specified, dwCallback in the MIDIOPENDESC structure is assumed to be a handle to a thread.

CALLBACK_WINDOW

If this flag is specified, dwCallback in the MIDIOPENDESC structure is assumed to be a window handle.

MIDI_IO_COOKED

If this flag is specified, the device is opened in stream mode and the driver receives stream messages. The driver must be able to handle any contingencies that arise. For example, the driver must be able to play short messages and system-exclusive messages asynchronously to the stream.

+ +## Return value + +The **modMessage** function returns MMSYSERR\_NOERROR if the operation is successful. Otherwise it returns one of the error messages in the following table. + + + + + + + + + + + + + + + + + + + + + + +
Return codeDescription
MMSYSERR_NOTENABLED

The driver failed to load or initialize.

MMSYSERR_ALLOCATED

The MIDI device is already allocated by the maximum number of clients that the driver supports or the device cannot be opened because of system resource limitations other than memory.

MMSYSERR_NOMEM

The device cannot be opened because of a failure to allocate or lock memory.

+ +## Remarks + +The driver must be able to determine the number of clients it can allow to use a particular device. After a device is opened for the maximum number of clients that the driver supports, the driver returns MMSYSERR\_ALLOCATED for any additional requests to open the device. If the open operation is successful, the driver uses the [DriverCallback](/windows/win32/api/mmiscapi/nf-mmiscapi-drivercallback) function to send the client a [**MOM\_OPEN**](mom-open.md) message. + +## Requirements + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Available in Windows XP and later Windows operating systems.

Header

Mmddk.h (include Mmddk.h, Mmsystem.h, or Windows.h)
+ +## See also + +[**modMessage**](mod-message.md) + +[**MIDIOPENDESC**](/windows/win32/api/mmddk/ns-mmddk-midiopendesc) + +[DriverCallback](/windows/win32/api/mmiscapi/nf-mmiscapi-drivercallback) + +[**MOM\_OPEN**](mom-open.md) diff --git a/windows-driver-docs-pr/audio/modm-pause.md b/windows-driver-docs-pr/audio/modm-pause.md new file mode 100644 index 0000000000..3c8bddbc80 --- /dev/null +++ b/windows-driver-docs-pr/audio/modm-pause.md @@ -0,0 +1,73 @@ +--- +title: MODM_PAUSE function (Windows Drivers) +description: Learn more about the MODM_PAUSE function. +keywords: +- mmddk/modMessage +- modMessage +ms.date: 03/06/2023 +ms.topic: reference +--- + +# MODM\_PAUSE function + +WINMM sends the `MODM_PAUSE` message to the [**modMessage**](mod-message.md) function of a MIDI output driver to temporarily pause output requests. Playback of streams stops but no buffers are marked as done. + +## Syntax + +``` c++ +DWORD modMessage( +  UINT      uDeviceID, +  UINT      uMsg, +  DWORD_PTR dwUser, +  DWORD_PTR dwParam1, +  DWORD_PTR dwParam2 +); +``` + +## Parameters + +- *uDeviceID* + Specifies the ID of the target device. Device IDs are sequential and have an initial value of zero and a final value that is equal to one less than the number of devices that the driver supports. + +- *uMsg* + WINMM sets this parameter to **MODM\_PAUSE** when it calls **modMessage** to process this message. + +- *dwUser* + Use this parameter to return instance data to the driver. Drivers that support multiple clients can use this instance data to track the client that is associated with the message. + +- *dwParam1* + Not used. + +- *dwParam2* + Not used. + +## Return value + +The **modMessage** function returns MMSYSERR\_NOERROR if the operation was successful. Otherwise, it returns MMSYSERR\_NOTENABLED to indicate that the driver failed to load or initialize. + +## Remarks + +The driver must halt MIDI playback in the current position. The driver must then turn off all notes that are currently on. + +## Requirements + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Available in Windows XP and later Windows operating systems.

Header

Mmddk.h (include Mmddk.h, Mmsystem.h, or Windows.h)
+ +## See also + +[**modMessage**](mod-message.md) diff --git a/windows-driver-docs-pr/audio/modm-prepare.md b/windows-driver-docs-pr/audio/modm-prepare.md new file mode 100644 index 0000000000..fb209e0066 --- /dev/null +++ b/windows-driver-docs-pr/audio/modm-prepare.md @@ -0,0 +1,98 @@ +--- +title: MODM_PREPARE function (Windows Drivers) +description: Learn more about the MODM_PREPARE function. +keywords: +- mmddk/modMessage +- modMessage +ms.date: 03/06/2023 +ms.topic: reference +--- + +# MODM\_PREPARE function + +WINMM sends the `MODM_PREPARE` message to the [**modMessage**](mod-message.md) function of a MIDI output driver to request that the driver configure a system-exclusive data block for output. If data blocks are accessed at interrupt time, they must be page-locked to ensure that the memory is not swapped out to disk. + +## Syntax + +``` c++ +DWORD modMessage( +  UINT      uDeviceID, +  UINT      uMsg, +  DWORD_PTR dwUser, +  DWORD_PTR dwParam1, +  DWORD_PTR dwParam2 +); +``` + +## Parameters + +- *uDeviceID* + Specifies the ID of the target device. Device IDs are sequential and have an initial value of zero and a final value that is equal to one less than the number of devices that the driver supports. + +- *uMsg* + WINMM sets this parameter to **MODM\_PREPARE** when it calls **modMessage** to process this message. + +- *dwUser* + Use this parameter to return instance data to the driver. Drivers that support multiple clients can use this instance data to track the client that is associated with the message. + +- *dwParam1* + Specifies a far pointer to the [MIDIHDR](/windows/win32/api/mmeapi/ns-mmeapi-midihdr) structure that identifies the data block. + +- *dwParam2* + Specifies the size of the **MIDIHDR** structure. + +## Return value + +The **modMessage** function returns MMSYSERR\_NOERROR if the operation is successful. Otherwise, it returns one of the error messages in the following table. + + + + + + + + + + + + + + + + + + +
Return codeDescription
MMSYSERR_NOTENABLED

The driver failed to load or initialize.

MMSYSERR_NOTSUPPORTED

The driver does not support this message.

+ +## Remarks + +Driver support for this message is optional. If a driver supports this message, it must also support [**MODM\_UNPREPARE**](modm-unprepare.md). + +The default response for this message is to return MMSYSERR\_NOTSUPPORTED. In this case, WINMM converts the memory segment to page-locked memory for the driver. If a driver has to perform other operations so that it can prepare a data block for output, it must set the MHDR\_PREPARED bit in the **dwFlags** field of the **MIDIHDR** structure and return MMSYSERR\_NOERROR. In this case, WINMM assumes the driver has prepared the data block and does not page-lock the memory. + +## Requirements + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Available in Windows XP and later Windows operating systems.

Header

Mmddk.h (include Mmddk.h, Mmsystem.h, or Windows.h)
+ +## See also + +[**modMessage**](mod-message.md) + +[MIDIHDR](/windows/win32/api/mmeapi/ns-mmeapi-midihdr) + +[**MODM\_UNPREPARE**](modm-unprepare.md) diff --git a/windows-driver-docs-pr/audio/modm-properties.md b/windows-driver-docs-pr/audio/modm-properties.md new file mode 100644 index 0000000000..d95b5f03b8 --- /dev/null +++ b/windows-driver-docs-pr/audio/modm-properties.md @@ -0,0 +1,117 @@ +--- +title: MODM_PROPERTIES function (Windows Drivers) +description: Learn more about the MODM_PROPERTIES function. +keywords: +- mmddk/modMessage +- modMessage +ms.date: 03/06/2023 +ms.topic: reference +--- + +# MODM\_PROPERTIES function + +WINMM sends the `MODM_PROPERTIES` message to the [**modMessage**](mod-message.md) function of a MIDI output driver to change the properties of the output stream. + +## Syntax + +``` c++ +DWORD modMessage( +  UINT      uDeviceID, +  UINT      uMsg, +  DWORD_PTR dwUser, +  DWORD_PTR dwParam1, +  DWORD_PTR dwParam2 +); +``` + +## Parameters + +- *uDeviceID* + Specifies the ID of the target device. Device IDs are sequential and have with an initial value of zero and a final value that is equal to one less than the number of devices that the driver supports. + +- *uMsg* + WINMM sets this parameter to **MODM\_PROPERTIES** when it calls **modMessage** to process this message. + +- *dwUser* + Use this parameter to return instance data to the driver. Drivers that support multiple clients can use this instance data to track the client that is associated with the message. + +- *dwParam1* + Contains a far pointer to a structure that contains information about the stream. + +- *dwParam2* + Contains flags that specify the operation and property. The property flags are set in the lower 30 bits of the value. These property bits are combined with one of the flags in the following table, by using the logical OR operator. + + + + + + + + + + + + + + + + + + +
FlagMeaning

MIDIPROP_SET

Tells the driver to set the specified property.

MIDIPROP_GET

Tells the driver to read (get) the specified property.

+ +## Return value + +The **modMessage** function returns MMSYSERR\_NOERROR if the operation is successful. Otherwise, it returns one of the error messages in the following table. + + + + + + + + + + + + + + + + + + +
Return codeDescription
MMSYSERR_NOTENABLED

The driver failed to load or initialize.

MMSYSERR_INVALIDPARAM

The specified property or property value is invalid.

+ +## Remarks + +For more information about the properties of a MIDI data stream, see [midiStreamProperties](/windows/win32/api/mmeapi/nf-mmeapi-midistreamproperty). Also see [MIDIPROPTEMPO](/windows/win32/api/mmeapi/ns-mmeapi-midiproptimediv). + +## Requirements + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Available in Windows XP and later Windows operating systems.

Header

Mmddk.h (include Mmddk.h, Mmsystem.h, or Windows.h)
+ +## See also + +[**modMessage**](mod-message.md) + +[midiStreamProperties](/windows/win32/api/mmeapi/nf-mmeapi-midistreamproperty) + +[MIDIPROPTIMEDIV](/windows/win32/api/mmeapi/ns-mmeapi-midiproptimediv) + +[MIDIPROPTEMPO](/windows/win32/api/mmeapi/ns-mmeapi-midiproptempo) diff --git a/windows-driver-docs-pr/audio/modm-reset.md b/windows-driver-docs-pr/audio/modm-reset.md new file mode 100644 index 0000000000..5b62e9012a --- /dev/null +++ b/windows-driver-docs-pr/audio/modm-reset.md @@ -0,0 +1,81 @@ +--- +title: MODM_RESET function (Windows Drivers) +description: Learn more about the MODM_RESET function. +keywords: +- mmddk/modMessage +- modMessage +ms.date: 03/06/2023 +ms.topic: reference +--- + +# MODM\_RESET function + +WINMM sends the `MODM_RESET` message to the [**modMessage**](mod-message.md) function of a MIDI output driver to stop output from the output queue and to turn off any notes that are playing. + +## Syntax + +``` c++ +DWORD modMessage( +  UINT      uDeviceID, +  UINT      uMsg, +  DWORD_PTR dwUser, +  DWORD_PTR dwParam1, +  DWORD_PTR dwParam2 +); +``` + +## Parameters + +- *uDeviceID* + Specifies the ID of the target device. Device IDs are sequential and have an initial value of zero and a final value that is equal to one less than the number of devices that the driver supports. + +- *uMsg* + WINMM sets this parameter to **MODM\_RESET** when it calls **modMessage** to process this message. + +- *dwUser* + Use this parameter to return instance data to the driver. Drivers that support multiple clients can use this instance data to track the client that is associated with the message. + +- *dwParam1* + Not used. + +- *dwParam2* + Not used. + +## Return value + +The **modMessage** function returns MMSYSERR\_NOERROR if the operation is successful. Otherwise, it returns MMSYSERR\_NOTENABLED to indicate that the driver failed to load or initialize. + +## Remarks + +If the output queue of the MIDI output driver is not empty, it must stop all pending data blocks and mark them as done by setting the MHDR\_DONE bit in the **dwFlags** field of the [MIDIHDR](/windows/win32/api/mmeapi/ns-mmeapi-midihdr) structure for each block. The driver must then notify the client by using [DriverCallback](/windows/win32/api/mmiscapi/nf-mmiscapi-drivercallback) to send a [**MOM\_DONE**](mom-done.md) message for each data block. + +If the device is an output port, the driver must send a MIDI note-off event for all 128 notes on all 16 channels. Optionally, the driver can track the notes that are turned on and send note-off events for only those notes. In addition, the driver must send a 'damper pedal off' event (controller 0x40) for each channel. If the device is an internal synthesizer, the driver must turn off any notes that are playing. + +## Requirements + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Available in Windows XP and later Windows operating systems.

Header

Mmddk.h (include Mmddk.h, Mmsystem.h, or Windows.h)
+ +## See also + +[**modMessage**](mod-message.md) + +[MIDIHDR](/windows/win32/api/mmeapi/ns-mmeapi-midihdr) + +[DriverCallback](/windows/win32/api/mmiscapi/nf-mmiscapi-drivercallback) + +[**MOM\_DONE**](mom-done.md) diff --git a/windows-driver-docs-pr/audio/modm-restart.md b/windows-driver-docs-pr/audio/modm-restart.md new file mode 100644 index 0000000000..938b341a76 --- /dev/null +++ b/windows-driver-docs-pr/audio/modm-restart.md @@ -0,0 +1,77 @@ +--- +title: MODM_RESTART function (Windows Drivers) +description: Learn more about the MODM_RESTART function. +keywords: +- mmddk/modMessage +- modMessage +ms.date: 03/06/2023 +ms.topic: reference +--- + +# MODM\_RESTART function + +WINMM sends the `MODM_RESTART` message to the [**modMessage**](mod-message.md) function of a MIDI output driver to restart playback after a [**MODM\_PAUSE**](modm-pause.md). + +## Syntax + +``` c++ +DWORD modMessage( +  UINT      uDeviceID, +  UINT      uMsg, +  DWORD_PTR dwUser, +  DWORD_PTR dwParam1, +  DWORD_PTR dwParam2 +); +``` + +## Parameters + +- *uDeviceID* + Specifies the ID of the target device. Device IDs are sequential and have an initial value of zero and a final value that is equal to one less than the number of devices that the driver supports. + +- *uMsg* + WINMM sets this parameter to **MODM\_RESTART** when it calls **modMessage** to process this message. + +- *dwUser* + Use this parameter to return instance data to the driver. Drivers that support multiple clients can use this instance data to track the client that is associated with the message. + +- *dwParam1* + Not used. + +- *dwParam2* + Not used. + +## Return value + +The **modMessage** function returns MMSYSERR\_NOERROR if the operation is successful. Otherwise, it returns MMSYSERR\_NOTENABLED to indicate that the driver failed to load or initialize. + +## Remarks + +The MIDI output device driver must restart MIDI playback at the current position. + +**MODM\_PAUSE** and `MODM_RESTART` message pairs cannot be nested. **MODM\_PAUSE** messages that are received while the driver is already in the paused state must be ignored; playback will start on the first `MODM_RESTART` message that is received regardless of the number of **MODM\_PAUSE** that messages were received. Likewise, `MODM_RESTART` messages that are received while the driver is already in play mode must be ignored. MMSYSERR\_NOERROR must be returned in either case. + +## Requirements + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Available in Windows XP and later Windows operating systems.

Header

Mmddk.h (include Mmddk.h, Mmsystem.h, or Windows.h)
+ +## See also + +[**modMessage**](mod-message.md) + +[**MODM\_PAUSE**](modm-pause.md) diff --git a/windows-driver-docs-pr/audio/modm-setvolume.md b/windows-driver-docs-pr/audio/modm-setvolume.md new file mode 100644 index 0000000000..2e436c08b5 --- /dev/null +++ b/windows-driver-docs-pr/audio/modm-setvolume.md @@ -0,0 +1,96 @@ +--- +title: MODM_SETVOLUME function (Windows Drivers) +description: Learn more about the MODM_SETVOLUME function. +keywords: +- mmddk/modMessage +- modMessage +ms.date: 03/06/2023 +ms.topic: reference +--- + +# MODM\_SETVOLUME function + +WINMM sends the `MODM_SETVOLUME` message to the [**modMessage**](mod-message.md) function of a MIDI output driver to set the volume for a MIDI device. + +## Syntax + +``` c++ +DWORD modMessage( +  UINT      uDeviceID, +  UINT      uMsg, +  DWORD_PTR dwUser, +  DWORD_PTR dwParam1, +  DWORD_PTR dwParam2 +); +``` + +## Parameters + +- *uDeviceID* + Specifies the ID of the target device. Device IDs are sequential and have an initial value of zero and a final value that is equal to one less than the number of devices that the driver supports. + +- *uMsg* + WINMM sets this parameter to **MODM\_SETVOLUME** when it calls **modMessage** to process this message. + +- *dwUser* + Use this parameter to return instance data to the driver. Drivers that support multiple clients can use this instance data to track the client that is associated with the message. + +- *dwParam1* + This parameter specifies the new volume level. The high-order word contains the right channel setting and the low-order word contains the left channel setting. A value of zero is silence, and a value of 0xFFFF is full volume. If the driver does not support both left and right channel volume changes, it uses the volume specified in the low-order word. The driver will typically not support the full 16 bits of volume control and must truncate the lower bits if necessary. However, the original volume level set with MODM\_SETVOLUME must be returned with [**MODM\_GETVOLUME**](modm-getvolume.md). + +- *dwParam2* + Not used. + +## Return value + +The **modMessage** function returns MMSYSERR\_NOERROR if the operation was successful. Otherwise, it returns one of the error messages in the following table. + + + + + + + + + + + + + + + + + + +
Return codeDescription
MMSYSERR_NOTENABLED

The driver failed to load or initialize.

MMSYSERR_NOTSUPPORTED

The driver does not support changes to volume level.

+ +## Remarks + +This volume level is the final output volume; therefore, only drivers for internal synthesizer devices can support volume level changes. Drivers for MIDI output ports must return a MMSYSERR\_NOTSUPPORTED error for this message. Support for volume level changes is optional for internal synthesizer devices. When a driver receives a [**MODM\_GETDEVCAPS**](modm-getdevcaps.md) message, it must indicate support for volume level changes by setting or clearing the MIDICAPS\_VOLUME and MIDICAPS\_LRVOLUME bits in the **dwSupport** field of the [MIDIOUTCAPS](/windows/win32/api/mmeapi/ns-mmeapi-midioutcaps) data structure. If a driver supports the **MODM\_SETVOLUME** message, it must also support **MODM\_GETVOLUME**. + +## Requirements + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Available in Windows XP and later Windows operating systems.

Header

Mmddk.h (include Mmddk.h, Mmsystem.h, or Windows.h)
+ +## See also + +[**modMessage**](mod-message.md) + +[**MODM\_GETDEVCAPS**](modm-getdevcaps.md) + +[MIDIOUTCAPS](/windows/win32/api/mmeapi/ns-mmeapi-midioutcaps) diff --git a/windows-driver-docs-pr/audio/modm-stop.md b/windows-driver-docs-pr/audio/modm-stop.md new file mode 100644 index 0000000000..6d237e6ca1 --- /dev/null +++ b/windows-driver-docs-pr/audio/modm-stop.md @@ -0,0 +1,81 @@ +--- +title: MODM_STOP function (Windows Drivers) +description: Learn more about the MODM_STOP function. +keywords: +- mmddk/modMessage +- modMessage +ms.date: 03/06/2023 +ms.topic: reference +--- + +# MODM\_STOP function + +WINMM sends the `MODM_STOP` message to the [**modMessage**](mod-message.md) function of a MIDI output driver to stop output from the output queue and to turn off any notes that are playing. + +## Syntax + +``` c++ +DWORD modMessage( +  UINT      uDeviceID, +  UINT      uMsg, +  DWORD_PTR dwUser, +  DWORD_PTR dwParam1, +  DWORD_PTR dwParam2 +); +``` + +## Parameters + +- *uDeviceID* + Specifies the ID of the target device. Device IDs are sequential and have an initial value of zero and a final value that is equal to one less than the number of devices that the driver supports. + +- *uMsg* + WINMM sets this parameter to **MODM\_STOP** when it calls **modMessage** to process this message. + +- *dwUser* + Use this parameter to return instance data to the driver. Drivers that support multiple clients can use this instance data to track the client that is associated with the message. + +- *dwParam1* + Not used. + +- *dwParam2* + Not used. + +## Return value + +The **modMessage** function returns MMSYSERR\_NOERROR if the operation is successful. Otherwise it returns MMSYSERR\_NOTENABLED to indicate that the driver failed to load or initialize. + +## Remarks + +If the output queue of the MIDI output driver is not empty, it must stop all pending data blocks and mark them as done by setting the MHDR\_DONE bit in the **dwFlags** field of the [MIDIHDR](/windows/win32/api/mmeapi/ns-mmeapi-midihdr) structure for each block. The driver must then notify the client by using [DriverCallback](/windows/win32/api/mmiscapi/nf-mmiscapi-drivercallback) to send a [**MOM\_DONE**](mom-done.md) message for each data block. + +The driver should send a note-off event for all notes that are currently turned on. In addition, the driver should send a damper pedal off event (controller 0x40) for each channel. If the device is an internal synthesizer, the driver should turn off any notes that are playing. + +## Requirements + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Available in Windows XP and later Windows operating systems.

Header

Mmddk.h (include Mmddk.h, Mmsystem.h, or Windows.h)
+ +## See also + +[**modMessage**](mod-message.md) + +[DriverCallback](/windows/win32/api/mmiscapi/nf-mmiscapi-drivercallback) + +[MIDIHDR](/windows/win32/api/mmeapi/ns-mmeapi-midihdr) + +[**MOM\_DONE**](mom-done.md) diff --git a/windows-driver-docs-pr/audio/modm-strmdata.md b/windows-driver-docs-pr/audio/modm-strmdata.md new file mode 100644 index 0000000000..ab6bc40845 --- /dev/null +++ b/windows-driver-docs-pr/audio/modm-strmdata.md @@ -0,0 +1,83 @@ +--- +title: MODM_STRMDATA function (Windows Drivers) +description: Learn more about the MODM_STRMDATA function. +keywords: +- mmddk/modMessage +- modMessage +ms.date: 03/06/2023 +ms.topic: reference +--- + +# MODM\_STRMDATA function + +WINMM sends the `MODM_STRMDATA` message to the [**modMessage**](mod-message.md) function of a MIDI output driver to get the MIDI output device to send stream data. + +## Syntax + +``` c++ +DWORD modMessage( +  UINT      uDeviceID, +  UINT      uMsg, +  DWORD_PTR dwUser, +  DWORD_PTR dwParam1, +  DWORD_PTR dwParam2 +); +``` + +## Parameters + +- *uDeviceID* + Specifies the ID of the target device. Device IDs are sequential and have an initial value of zero and a final value that is equal to one less than the number of devices that the driver supports. + +- *uMsg* + WINMM sets this parameter to **MODM\_STRMDATA** when it calls **modMessage** to process this message. + +- *dwUser* + Use this parameter to return instance data to the driver. Drivers that support multiple clients can use this instance data to track the client that is associated with the message. + +- *dwParam1* + This parameter specifies a far pointer to [MIDIHDR](/windows/win32/api/mmeapi/ns-mmeapi-midihdr) structure that contains data in the stream buffer format. + +- *dwParam2* + This parameter specifies the size, in bytes, of the **MIDIHDR** structure. + +## Return value + +The **modMessage** function returns MMSYSERR\_NOERROR if the operation was successful. Otherwise, it returns MMSYSERR\_NOTENABLED to indicate that the driver failed to load or initialize. + +## Remarks + +The **dwStreamID** member of the [MIDIEVENT](/windows/win32/api/mmeapi/ns-mmeapi-midievent) structure is documented as reserved in the Windows SDK documentation. This member actually contains the destination of the given event. The driver must process the event only under the following circumstances: + +- *dwStreamID* matches one of the stream identifiers given in the array that is specified by the **rgIds** member of the [**MIDIOPENDESC**](/windows/win32/api/mmddk/ns-mmddk-midiopendesc) structure (specified in the [**MODM\_OPEN**](modm-open.md) message). In this case, the driver must process the event on the port to which the stream identifier was bound by means of a device identifier in the **MODM\_OPEN** message. + +- *dwStreamID* contains a -1 (0xFFFFFFFFL). In this case, the driver must process the event for all ports that are open on this stream. + +## Requirements + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Available in Windows XP and later Windows operating systems.

Header

Mmddk.h (include Mmddk.h, Mmsystem.h, or Windows.h)
+ +## See also + +[**modMessage**](mod-message.md) + +[MIDIHDR](/windows/win32/api/mmeapi/ns-mmeapi-midihdr) + +[MIDIEVENT](/windows/win32/api/mmeapi/ns-mmeapi-midievent) + +[**MIDIOPENDESC**](/windows/win32/api/mmddk/ns-mmddk-midiopendesc) diff --git a/windows-driver-docs-pr/audio/modm-unprepare.md b/windows-driver-docs-pr/audio/modm-unprepare.md new file mode 100644 index 0000000000..a734264ef5 --- /dev/null +++ b/windows-driver-docs-pr/audio/modm-unprepare.md @@ -0,0 +1,79 @@ +--- +title: MODM_UNPREPARE function (Windows Drivers) +description: Learn more about the MODM_UNPREPARE function. +keywords: +- mmddk/modMessage +- modMessage +ms.date: 03/06/2023 +ms.topic: reference +--- + +# MODM\_UNPREPARE function + +WINMM sends the `MODM_UNPREPARE` message to the [**modMessage**](mod-message.md) function of a MIDI output driver to clean up the memory segment that was configured by [**MODM\_PREPARE**](modm-prepare.md). + +## Syntax + +``` c++ +DWORD modMessage( +  UINT      uDeviceID, +  UINT      uMsg, +  DWORD_PTR dwUser, +  DWORD_PTR dwParam1, +  DWORD_PTR dwParam2 +); +``` + +## Parameters + +- *uDeviceID* + Specifies the ID of the target device. Device IDs are sequential and have an initial value of zero and a final value that is equal to one less than the number of devices that the driver supports. + +- *uMsg* + WINMM sets this parameter to **MODM\_UNPREPAE** when it calls **modMessage** to process this message. + +- *dwUser* + Use this parameter to return instance data to the driver. Drivers that support multiple clients can use this instance data to track the client that is associated with the message. + +- *dwParam1* + Specifies a far pointer to a [MIDIHDR](/windows/win32/api/mmeapi/ns-mmeapi-midihdr) structure that identifies the data block. + +- *dwParam2* + Specifies the size of the **MIDIHDR** structure. + +## Return value + +The **modMEssage** function returns MMSYSERR\_NOERROR if the operation is successful. Otherwise, it returns MMSYSERR\_NOTENABLED to indicate that the driver failed to load or initialize. + +## Remarks + +Driver support for this message is optional. If a driver supports the [**MODM\_PREPARE**](modm-prepare.md) message, it must also support `MODM_UNPREPARE`. + +The default response for this message is to return MMSYSERR\_NOTSUPPORTED. In this case, Mmsystem.dll cleans up the preparation that was previously done on the memory block. If a driver performs the PREPARE operation, it must clean up the preparation and reset the MHDR\_PREPARED flag in the **dwFlags** field of the **MIDIHDR** structure. + +## Requirements + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Available in Windows XP and later Windows operating systems.

Header

Mmddk.h (include Mmddk.h, Mmsystem.h, or Windows.h)
+ +## See also + +[**modMessage**](mod-message.md) + +[**MODM\_PREPARE**](modm-prepare.md) + +[MIDIHDR](/windows/win32/api/mmeapi/ns-mmeapi-midihdr) diff --git a/windows-driver-docs-pr/audio/mom-close.md b/windows-driver-docs-pr/audio/mom-close.md new file mode 100644 index 0000000000..a7634083ee --- /dev/null +++ b/windows-driver-docs-pr/audio/mom-close.md @@ -0,0 +1,67 @@ +--- +title: MOM_CLOSE function (Windows Drivers) +description: Learn more about the MOM_CLOSE function. +keywords: +- mmddk/modMessage +- modMessage +ms.date: 03/06/2023 +ms.topic: reference +--- + +# MOM\_CLOSE function + +WINMM sends the **MOM\_CLOSE** message to the [**modMessage**](mod-message.md) function of a MIDI output driver in response to a call from a client application. + +## Syntax + +``` c++ +DWORD modMessage( +  UINT      uDeviceID, +  UINT      uMsg, +  DWORD_PTR dwUser, +  DWORD_PTR dwParam1, +  DWORD_PTR dwParam2 +); +``` + +## Parameters + +- *uDeviceID* + Specifies the ID of the target device. Device IDs are sequential and have an initial value of zero and a final value that is equal to one less than the number of devices that the driver supports. + +- *uMsg* + WINMM sets this parameter to **MOM\_CLOSE** when it calls [**modMessage**](mod-message.md) to process this message. + +- *dwUser* + The driver sets this parameter to match the instance data from the client that called it. + +- *dwParam1* + Not used. + +- *dwParam2* + Not used. + +## Return value + +None + +## Remarks + +## Requirements + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Available in Windows XP and later Windows operating systems.

Header

Mmddk.h (include Mmddk.h, Mmsystem.h, or Windows.h)
diff --git a/windows-driver-docs-pr/audio/mom-done.md b/windows-driver-docs-pr/audio/mom-done.md new file mode 100644 index 0000000000..701ce8168a --- /dev/null +++ b/windows-driver-docs-pr/audio/mom-done.md @@ -0,0 +1,71 @@ +--- +title: MOM_DONE function (Windows Drivers) +description: Learn more about the MOM_DONE function. +keywords: +- mmddk/modMessage +- modMessage +ms.date: 03/06/2023 +ms.topic: reference +--- + +# MOM\_DONE function + +WINMM sends the **MOM\_DONE** message to the [**modMessage**](mod-message.md) function of MIDI output driver, to return a system-exclusive data block to the client application. + +## Syntax + +``` c++ +DWORD modMessage( +  UINT      uDeviceID, +  UINT      uMsg, +  DWORD_PTR dwUser, +  DWORD_PTR dwParam1, +  DWORD_PTR dwParam2 +); +``` + +## Parameters + +- *uDeviceID* + Specifies the ID of the target device. Device IDs are sequential that has an initial value of zero and a final value that is equal to one less than the number of devices that the driver supports. + +- *uMsg* + WINMM sets this parameter to **MOM\_DONE** when it calls [**modMessage**](mod-message.md) to process this message. + +- *dwUser* + The driver sets this parameter to match the instance data from the client that called it. + +- *dwParam1* + Specifies a far pointer to a [MIDIHDR](/windows/win32/api/mmeapi/ns-mmeapi-midihdr) structure that identifies the data block. + +- *dwParam2* + Not used. + +## Return value + +None + +## Remarks + +## Requirements + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Available in Windows XP and later Windows operating systems.

Header

Mmddk.h (include Mmddk.h, Mmsystem.h, or Windows.h)
+ +## See also + +[MIDIHDR](/windows/win32/api/mmeapi/ns-mmeapi-midihdr) diff --git a/windows-driver-docs-pr/audio/mom-open.md b/windows-driver-docs-pr/audio/mom-open.md new file mode 100644 index 0000000000..2a88b95f9e --- /dev/null +++ b/windows-driver-docs-pr/audio/mom-open.md @@ -0,0 +1,67 @@ +--- +title: MOM_OPEN function (Windows Drivers) +description: Learn more about the MOM_OPEN function. +keywords: +- mmddk/modMessage +- modMessage +ms.date: 03/06/2023 +ms.topic: reference +--- + +# MOM\_OPEN function + +WINMM sends the **MOM\_OPEN** message to the [**modMessage**](mod-message.md) function of a MIDI output driver. + +## Syntax + +``` c++ +DWORD modMessage( +  UINT      uDeviceID, +  UINT      uMsg, +  DWORD_PTR dwUser, +  DWORD_PTR dwParam1, +  DWORD_PTR dwParam2 +); +``` + +## Parameters + +- *uDeviceID* + Specifies the ID of the target device. Device IDs are sequential and have an initial value of zero and a final value that is equal to one less than the number of devices that the driver supports. + +- *uMsg* + WINMM sets this parameter to **MOM\_OPEN** when it calls [**modMessage**](mod-message.md) to process this message. + +- *dwUser* + The driver sets this parameter to match the instance data from the client that called it. + +- *dwParam1* + Not used. + +- *dwParam2* + Not used. + +## Return value + +None + +## Remarks + +## Requirements + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Available in Windows XP and later Windows operating systems.

Header

Mmddk.h (include Mmddk.h, Mmsystem.h, or Windows.h)
diff --git a/windows-driver-docs-pr/audio/obsolete-kernel-mode-driver-support-functions.md b/windows-driver-docs-pr/audio/obsolete-kernel-mode-driver-support-functions.md index 6a0cbd221e..b9a5f50750 100644 --- a/windows-driver-docs-pr/audio/obsolete-kernel-mode-driver-support-functions.md +++ b/windows-driver-docs-pr/audio/obsolete-kernel-mode-driver-support-functions.md @@ -1,9 +1,11 @@ --- title: Obsolete Kernel-Mode Driver-Support Functions description: Obsolete Kernel-Mode Driver-Support Functions -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # Obsolete Kernel-Mode Driver-Support Functions diff --git a/windows-driver-docs-pr/audio/obsolete-port-class-functions.md b/windows-driver-docs-pr/audio/obsolete-port-class-functions.md index d282117152..e456880cd3 100644 --- a/windows-driver-docs-pr/audio/obsolete-port-class-functions.md +++ b/windows-driver-docs-pr/audio/obsolete-port-class-functions.md @@ -1,9 +1,11 @@ --- title: Obsolete Port Class Functions description: Obsolete Port Class Functions -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # Obsolete Port Class Functions diff --git a/windows-driver-docs-pr/audio/obtaining-bluetooth-address-of-hf-device.md b/windows-driver-docs-pr/audio/obtaining-bluetooth-address-of-hf-device.md index 005109ce75..d02d0dbf52 100644 --- a/windows-driver-docs-pr/audio/obtaining-bluetooth-address-of-hf-device.md +++ b/windows-driver-docs-pr/audio/obtaining-bluetooth-address-of-hf-device.md @@ -6,16 +6,15 @@ ms.date: 04/20/2017 # Obtaining Bluetooth Address of HF Device - The Obtaining Bluetooth Address of HF Device topic demonstrate how the audio driver can obtain the Bluetooth address of a paired Hands-free (HF) device. The address string can be useful for uniquely identifying a particular paired HF device. For example, the address string can be used as the *ReferenceString* parameter that is passed to IoRegisterDeviceInterface, the *RefString* parameter that is passed to KsCreateFilterFactory, or the *Name* parameter that is passed to PcRegisterSubdevice. -Note that the GUID\_DEVINTERFACE\_BLUETOOTH\_HFP\_SCO\_HCIBYPASS device interface symbolic link is also unique for each paired HF device, but this string can be too long for some purposes. +Note that the GUID_DEVINTERFACE_BLUETOOTH_HFP_SCO_HCIBYPASS device interface symbolic link is also unique for each paired HF device, but this string can be too long for some purposes. The IoHelperGetDevicePdo routine shown in the following code example is a utility function used by IoHelperGetDeviceBluetoothAddress. Such functions can be called while the audio driver is handling a PnP interface arrival notification. The audio driver gets the device object from IoGetDeviceObjectPointer and passes it to IoHelperGetDeviceBluetoothAddress. -```ManagedCPlusPlus +```cpp _IRQL_requires_(PASSIVE_LEVEL) NTSTATUS IoHelperGetDevicePdo( @@ -199,8 +198,3 @@ Exit: } ``` -## Related topics -[Related Design Guidelines](related-design-guidelines.md) - - - diff --git a/windows-driver-docs-pr/audio/operating-system-upgrades.md b/windows-driver-docs-pr/audio/operating-system-upgrades.md index 16d31dc6db..2ca0608217 100644 --- a/windows-driver-docs-pr/audio/operating-system-upgrades.md +++ b/windows-driver-docs-pr/audio/operating-system-upgrades.md @@ -6,60 +6,123 @@ keywords: - adapter drivers WDK audio , operating system upgrades - Port Class audio adapters WDK , operating system upgrades - preserving audio settings WDK audio -- migration DLL WDK audio +- CAPX settings framework - migrating settings WDK audio -ms.date: 04/20/2017 +ms.date: 10/25/2022 --- # Operating System Upgrades +An audio device's driver settings can frequently be preserved across operating system upgrades. After the upgrade, the goal is to move user settings forward, while also ensuring that the audio endpoints accurately reflect the OS and driver capabilities. -## +## Audio endpoint migration process +During OS upgrades, an audio end point migration process may run. This process attempts to move as much information forward that is safe to do so. As you develop your audio driver, keep these migration behaviors in mind. -An audio device's driver and registry settings can frequently be preserved across operating system upgrades. The discussion below presents some guidelines for accomplishing this. +This endpoint migration process can run in the following situations. -### Preserving Audio Settings +- OS update. +- Audio Driver updates. This includes installing an audio extension driver or an AudioProcessingObject. For more information, see [Creating a componentized audio driver installation](audio-universal-drivers.md#creating-a-componentized-audio-driver-installation). +- The existing audio driver is reinstalled in place. This reinstallation can occur when the audio troubleshooter is run. This can also occur through the device manager by doing an "update driver" and selecting the driver that is already installed. +- AudioEndpointBuilder is serviced. This occurs whenever there is a bug fix in the AudioEndpointBuilder service that is updated in released versions of Windows. +- The firmware revision on a USB audio driver is changed. +- The audio driver changes the endpoint configuration via [**KSPROPERTY_JACK_DESCRIPTION3**](ksproperty-jack-description3.md). -An audio adapter driver can keep track of its current device settings--chiefly volume levels and mute settings--in the system registry. The driver typically stores these settings in the system-supplied driver key (represented by the INF keyword HKR) under the subkey "Settings". When the user alters these settings through a control panel or other audio application, the driver updates the appropriate registry entries. Each time the system boots, the driver restores the device settings from the registry. +### The audio endpoint migration process -When upgrading from Windows Me/98 to Windows XP or Windows 2000, the Windows installation program is unable to preserve these settings. +The audio endpoint migration process does the following. -However, when upgrading from Windows 98 to Windows Me, or from one NT-based operating system to another (for example, from Windows 2000 to Windows XP), the installation program leaves the driver's existing registry settings intact. Users largely prefer this behavior because it preserves the adjustments they have made to the system over time instead of forcing them to try to restore their settings manually each time they upgrade the operating system. +- Copies forward user-controlled endpoint properties. +- Copies forward CAPX properties. -Some proprietary drivers, however, blindly overwrite these registry settings with defaults each time they are installed. A better approach is for a driver to determine at installation time whether certain driver-specific registry entries already exist. If they do exist, the driver should preserve the settings that are contained in these entries instead of overwriting them. +The audio endpoint migration process does not do any of the following. -The directives in the add-registry section of the driver's INF file specify whether existing registry entries should be overwritten. For more information, see the description of the FLG\_ADDREG\_NOCLOBBER flag in [**INF AddReg Directive**](../install/inf-addreg-directive.md). +- Does not copy forward FXProperties prior to CAPX availability with Windows 11. +- It does not copy forward Properties that are not in the list of user settings known to the OS. + +Starting with Windows 11, a new "CAPX" settings framework is used to store settings. The Settings Framework allows APOs to expose methods for querying and modifying the property store for audio effects ("FX Property Store") on an audio endpoint. For more information, see [Windows 11 APIs for Audio Processing Objects](windows-11-apis-for-audio-processing-objects.md). + +### Matching the pre-upgrade endpoints to post upgrade endpoints + +The migration process matches the pre-upgrade endpoints to post upgrade endpoints using these two elements. + +- *Hardware Id* - For more information about the hardware Id, see [System-Wide Unique Device IDs](system-wide-unique-device-ids.md). +- *Reference string* - The use of the *reference string* is discussed below. + +Note that because new endpoints are created, caching mmdevice id's will not work during the end point migration process. + +#### Registered Subdevice + +The port class driver's [PcRegisterSubdevice function](/windows-hardware/drivers/ddi/portcls/nf-portcls-pcregistersubdevice) registers the subdevice, which is perceived as a device by the rest of the system. The function registers the device interface instance for a filter object that represents a subdevice on an audio adapter. The I/O manager appends the string specified by the Name parameter to the reference string that it uses to identify the instance. The modified reference string is useful for distinguishing among the subdevices in the audio adapter. For more information about reference strings, see [IoRegisterDeviceInterface](/windows-hardware/drivers/ddi/wdm/nf-wdm-ioregisterdeviceinterface). + +#### Reference string usage + +Audio endpoints are identified by the *reference string* passed to PnP when the KS interface was created, along with the pin ID for the external connector. Changing these values will cause a new audio endpoint to be created. This new audio endpoint will not contain the user settings associated to the prior reference string and connector pin ID. + +In cases where the hardware id is the same between two or more installed audio devices and the reference strings are also identical, the migration system will not be able to migrate settings properly due to failing to match the endpoints from prior to the migration to the endpoints after the migration. + +Installing multiple copies of the same root enumerated software audio devices on all versions of Windows, which all use the same hardware id and reference strings, will not migrate correctly. + +#### Prior to Windows 11 -### Migration DLL +For root enumerated software audio devices on systems prior to Windows 11, audio endpoints with the same reference string values will not migrate correctly. -During an upgrade from Windows Me/98 to an NT-based operating system (Windows 2000 and later), the Windows installation program treats a device driver that was installed under Windows Me/98 as incompatible and discards both the driver and its registry settings. +When creating a root enumerated software audio device that targeting Windows versions prior to Windows 11, a unique reference string value needs to be used for each audio endpoint to ensure a successful migration. -In addition, if the Windows 2000 setup program finds no in-box driver support for the device, the program immediately prompts the user to provide the driver software. In Windows XP and later, if the setup program is unable to find a suitable driver either in-box or at the Windows Update site, it waits until the upgrade has completed to inform the user of the missing driver. +#### Windows 11 and later -Although a driver cannot avoid the loss of its registry settings during such an upgrade, Microsoft recommends the use of a migration DLL to reinstall a compatible driver transparently to the user. For this purpose, Microsoft provides the Devupgrd migration DLL, which is included in the Setup Plug and Play samples in the Windows Driver Kit (WDK). The sample includes a help file that describes the migration DLL. +Root enumerated software audio devices on systems on and after Windows 11, without a hardware id, audio endpoints with the same reference string values will not migrate correctly. -The migration DLL should be used only with WDM drivers that are initially installed under Windows Me/98 but are also capable of running on Windows 2000 or Windows XP. Note that the migration DLL cannot upgrade drivers from Windows Me/98 to Windows Server 2003, Windows Vista, or later. It can only upgrade drivers from Windows Me/98 to Windows XP or Windows 2000. +When creating a root enumerated software audio device that targets Windows versions after Windows 11, a unique hardware id needs to be specified in the driver inf, and each root enumerated software audio device can only be installed a single time with that hardware id. To install multiple copies of the same driver, different reference strings must be used on each installation to ensure a successful migration. -During the upgrade from Windows Me/98 to Windows XP or Windows 2000, the migration DLL does the following: +### Reference string rules -- Reads the device driver's migration information from its location in the Windows Me/98 registry. +It is strongly recommended not to use the default "wave" and "topo" reference strings that are used in the audio sample driver(s). More descriptive reference strings should be used instead. Drivers which use the default reference strings have a risk of having their migration data lost or applied to the wrong device in the event that a hardware id is unavailable or matches some other driver using these reference strings. A reasonable strategy would be something like "ContosoSoftwareRender-output2". Including a unique vendor name helps to disambiguate the reference string. -- Adds the necessary information to the driver's INF file to ensure that the device installs properly under Windows XP or Windows 2000. +Reference strings must remain static for the audio driver installation, updates, OS updates, reboots, etc. If the reference string changes, a new audio endpoint will be created and user settings will not be copied from the previous endpoint to the new endpoint. -To make the migration information available later to the Windows XP or Windows 2000 setup program, the INF file that installs the device under Windows Me/98 should do the following: +#### Hardware Id Device Instance Name -- Copy the migration DLL to an INF-specified backup directory and add that directory's path name to the Windows Me/98 registry. +The audio driver Hardware Id is defined in the Models section of the INF file. The Hardware Id identifies at least one device, and references the DDInstall section of the INF file for that device. It also specifies a unique-to-the-model-section Hardware identifier (ID) for that device. For more information see, [INF Models section](../install/inf-models-section.md) and [INF DDInstall section](../install/inf-ddinstall-section.md). -- Add to the registry the device IDs that identify the devices that can migrate. +This INF file shows the Device Description from the DDInstall section in the Sysvad audio sample. + +```inf +[SYSVAD.NT$ARCH$] +%SYSVAD_SA.DeviceDesc%=SYSVAD_SA, Root\sysvad_ComponentizedAudioSample + +SYSVAD_SA.DeviceDesc="Virtual Audio Device (WDM) - Tablet Sample" +``` + +This INF file shows the how the Device Description would be customized by an OEM. + +```inf +[CONTOSO.NT$ARCH$] +%CONTOSO_SA.DeviceDesc%=CONTOSO_SA, Root\contoso_ContosoSoftwareRender + +CONTOSO_SA.DeviceDesc="Description of the Contoso Software Render Driver" +``` + +The hardware id that AudioEndpointBuilder will match on would be `Root\contoso_ContosoSoftwareRender` + +## Registry stored settings + +An audio adapter driver can keep track of its current device settings (chiefly volume levels and mute settings) in the system registry. The driver typically stores these settings in the system-supplied driver key (represented by the INF keyword HKR) under the subkey "Settings". When the user alters these settings through a control panel or other audio application, the driver updates the appropriate registry entries. Each time the system boots, the driver restores the device settings from the registry. + +Users largely prefer this behavior because it preserves the adjustments they have made to the system over time instead of forcing them to try to restore their settings manually each time they upgrade the operating system. + +Some drivers, however, blindly overwrite these settings with defaults each time they are installed. A better approach is for a driver to determine at installation time whether certain driver-specific entries already exist. If they do exist, the driver should preserve the settings that are contained in these entries instead of overwriting them. + +The directives in the add-registry section of the driver's INF file specify whether existing registry entries should be overwritten. For more information, see the description of the FLG\_ADDREG\_NOCLOBBER flag in [**INF AddReg Directive**](../install/inf-addreg-directive.md). -- Save backup copies of the device driver files (.sys and .inf) into INF-specified backup directories and add those directories' path names to the registry. +## See also -During the upgrade, the Windows XP or Windows 2000 setup program adds the backup directory names to the INF search path for the registered device IDs. +[**KSPROPERTY_JACK_DESCRIPTION3**](ksproperty-jack-description3.md) -As discussed above, the setup program discards the driver's registry settings during an upgrade from Windows Me/98 to Windows XP or Windows 2000. The driver reinstallation that is performed with the help of a migration DLL is a "clean install" in which the driver's volume, mute, and other settings assume their initial, default values. +[DEVPKEY_Device_DeviceDesc](../install/devpkey-device-devicedesc.md) -The Ac97 audio adapter sample in the Windows Driver Kit (WDK) contains an example of an INF file (Ac97smpl.inf) that migrates an audio driver from Windows Me/98 to Windows XP or Windows 2000. +[INF DDInstall section](../install/inf-ddinstall-section.md) - +[DCH Design Principles and Best Practices](../develop/dch-principles-best-practices.md) +[Windows 11 APIs for Audio Processing Objects](windows-11-apis-for-audio-processing-objects.md) \ No newline at end of file diff --git a/windows-driver-docs-pr/audio/opting-out-of-volume-level-persistence.md b/windows-driver-docs-pr/audio/opting-out-of-volume-level-persistence.md index adab6d66ac..9820de752e 100644 --- a/windows-driver-docs-pr/audio/opting-out-of-volume-level-persistence.md +++ b/windows-driver-docs-pr/audio/opting-out-of-volume-level-persistence.md @@ -1,12 +1,11 @@ --- title: Opting Out of Volume Level Persistence description: Opting Out of Volume Level Persistence -ms.date: 04/20/2017 +ms.date: 05/05/2023 --- # Opting Out of Volume Level Persistence - By default the volume level settings are maintained when you restart your computer. This default system behavior is referred to as *volume persistence*. If you do not want the volume levels to be maintained by the system after a computer restart, you can use an INF file at the time of installation of the audio adapter, to opt out of the default system behavior. You may want your driver to opt out of volume persistence if your driver had its own registry cache and sets the levels on the hardware itself, on driver load. @@ -16,19 +15,20 @@ To opt out of volume persistence using an INF file, use the [**AddProperty**](.. The following INF file fragment shows how to opt out of volume persistence: ```inf - ;; INF file fragment to show how to use AddProperty ;; to opt out of volume persistence ;; [Version] -Signature = "$CHICAGO$" +... Class = MEDIA -ClassGUID = {...} +ClassGUID = {4d36e96c-e325-11ce-bfc1-08002be10318} ... + [Manufacturer] -%MfgName% = CompanyName +%MfgName% = CompanyName,NTamd64 ... -[CompanyName] + +[CompanyName.NTamd64] %DeviceDescription% = HdAudModel, hw-id ;; ... other device models listed here @@ -50,8 +50,6 @@ DeviceDescription = "My WDM device driver" **Note**  The preceding INF file fragment, only shows the **Version** section and the sections relevant to the [**AddProperty**](../install/inf-addproperty-directive.md) directive. - - The **%MfgName% = CompanyName** line entry in the **Manufacturer** section references the **CompanyName** section where the model and hardware ID (hw-id) of the audio adapter are provided. This section in an INF file, where model and hw-id information is provided, is called the *models section*. The actual title of the section is user-defined and in the preceding example it is **CompanyName**. For more information about the models section of an INF file, see [**INF Models Section**](../install/inf-models-section.md). The models section, in turn, references the device driver install (DDInstall) section, where information is provided about other INF files that the setup program must copy. The actual title of this section is user-defined and in the preceding example it is **HdAudModel**. The **Needs=KS.Registration...** line entry provides information about the specific sections within the INF files, from which the setup program must retrieve data for installation @@ -65,6 +63,3 @@ The **HdAudModel** section shows two line entries with the first one commented o For more information about the AddProperty directive, see [**INF AddProperty Directive**](../install/inf-addproperty-directive.md). The property name that corresponds to the property category GUID and property ID in the preceding INF file fragment is PKEY\_AudioDevice\_DontPersistControls. - - - diff --git a/windows-driver-docs-pr/audio/pin-category-property.md b/windows-driver-docs-pr/audio/pin-category-property.md index b8e51a5416..35372a8892 100644 --- a/windows-driver-docs-pr/audio/pin-category-property.md +++ b/windows-driver-docs-pr/audio/pin-category-property.md @@ -14,7 +14,7 @@ keywords: - terminal identifiers WDK audio - GUIDs WDK audio - category GUIDs WDK audio -ms.date: 04/20/2017 +ms.date: 08/17/2022 --- # Pin Category Property @@ -339,11 +339,10 @@ When instantiating a USB audio device, the USBAudio class system driver queries A PortCls miniport driver does not necessarily use only the category GUIDs that appear in the preceding six tables. For example, a driver might define and use a custom pin category GUID to describe a pin type whose functional category falls outside the categories in the tables. Naturally, a custom pin category GUID is useful only to clients that recognize the GUID. -The audio subsystem maintains a list of pin category GUIDs and their associated friendly names in the system registry. The GUIDs and friendly names are stored in the registry path HKLM\\SYSTEM\\CurrentControlSet\\Control\\MediaCategories. The media class installer copies the GUID-name pairs into the registry from the Ks.inf file located in the Inf subfolder of the main Windows folder (for example, C:\\Windows\\Inf\\Ks.inf). +The audio subsystem maintains a list of pin category GUIDs and their associated friendly names in the system registry. The media class installer copies the GUID-name pairs into the registry from the Ks.inf file located in the Inf subfolder of the main Windows folder (for example, C:\\Windows\\Inf\\Ks.inf). -In Windows Vista and later, the operating system uses pin categories to associate friendly names with audio endpoint devices. For more information about how to associate friendly names with audio endpoint devices, see [Friendly Names for Audio Endpoint Devices](friendly-names-for-audio-endpoint-devices.md). +The operating system uses pin categories to associate friendly names with audio endpoint devices. For more information about how to associate friendly names with audio endpoint devices, see [Friendly Names for Audio Endpoint Devices](friendly-names-for-audio-endpoint-devices.md). -In Windows XP, Windows 2000, and Windows Millennium Edition, the operating system makes only limited use of pin categories. The [WDMAud system driver](user-mode-wdm-audio-components.md#wdmaud_system_driver) acts on behalf of the mixer API to translate pin category GUIDs into MIXERLINE\_COMPONENTTYPE\_*XXX* values for use by client applications. WDMAud recognizes only a subset of the pin category GUIDs that appear in the preceding six tables. In addition, for historical reasons, WDMAud recognizes two pin category GUIDs, KSCATEGORY\_AUDIO and PINNAME\_CAPTURE, that do not appear in the tables. For more information about the translation of pin categories to mixer lines, see [Topology Pins](topology-pins.md). For information about the mixer API, see the Windows SDK documentation. diff --git a/windows-driver-docs-pr/audio/pkey-apo-swfallback-processingmodes.md b/windows-driver-docs-pr/audio/pkey-apo-swfallback-processingmodes.md index 253dddde23..07a9f8ee74 100644 --- a/windows-driver-docs-pr/audio/pkey-apo-swfallback-processingmodes.md +++ b/windows-driver-docs-pr/audio/pkey-apo-swfallback-processingmodes.md @@ -47,7 +47,7 @@ AUDIO_SIGNALPROCESSINGMODE_COMMUNICATIONS = "{98951333-B9CD-48B1-A0A3-FF40682D73 HKR,"FX\\0",%PKEY_APO_SWFallback_ProcessingModes%,%REG_MULTI_SZ%,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT%,%AUDIO_SIGNALPROCESSINGMODE_MOVIE%,%AUDIO_SIGNALPROCESSINGMODE_COMMUNICATIONS% ``` -## Related topics +## Related topics [Media-Class INF Extensions](media-class-inf-extensions.md) diff --git a/windows-driver-docs-pr/audio/pkey-audiodevice-enableendpointbydefault.md b/windows-driver-docs-pr/audio/pkey-audiodevice-enableendpointbydefault.md index da93c1b67b..ae7719945c 100644 --- a/windows-driver-docs-pr/audio/pkey-audiodevice-enableendpointbydefault.md +++ b/windows-driver-docs-pr/audio/pkey-audiodevice-enableendpointbydefault.md @@ -1,7 +1,8 @@ --- title: PKEY\_AudioDevice\_EnableEndpointByDefault description: PKEY\_AudioDevice\_EnableEndpointByDefault -ms.date: 01/15/2020 +ms.date: 05/05/2023 +ms.topic: reference --- # PKEY\_AudioDevice\_EnableEndpointByDefault @@ -168,9 +169,9 @@ The following INF file snippet shows how to use **PKEY\_AudioDevice\_EnableEndpo ```inf [Version] -Signature="$Windows NT$" +... Class=MEDIA -ClassGuid= {4d36e96c-e325-11ce-bfc1-08002be10318} +ClassGuid={4d36e96c-e325-11ce-bfc1-08002be10318} ... [USBAudio] @@ -203,9 +204,9 @@ The following INF file snippet shows how a CD player is set up so that it is ena ```inf [Version] -Signature="$Windows NT$" +... Class=MEDIA -ClassGuid= {4d36e96c-e325-11ce-bfc1-08002be10318} +ClassGuid={4d36e96c-e325-11ce-bfc1-08002be10318} ... [USBAudio] diff --git a/windows-driver-docs-pr/audio/pkey-audiodevice-neversetasdefaultendpoint.md b/windows-driver-docs-pr/audio/pkey-audiodevice-neversetasdefaultendpoint.md index eef3760a03..985ad29a3a 100644 --- a/windows-driver-docs-pr/audio/pkey-audiodevice-neversetasdefaultendpoint.md +++ b/windows-driver-docs-pr/audio/pkey-audiodevice-neversetasdefaultendpoint.md @@ -1,9 +1,11 @@ --- title: PKEY\_AudioDevice\_NeverSetAsDefaultEndpoint description: PKEY\_AudioDevice\_NeverSetAsDefaultEndpoint -ms.date: 11/28/2017 +ms.date: 05/05/2023 +ms.topic: reference --- + # PKEY\_AudioDevice\_NeverSetAsDefaultEndpoint @@ -13,9 +15,9 @@ The following INF file excerpt shows how to use **PKEY\_AudioDevice\_NeverSetAsD ```inf [Version] -Signature="$Windows NT$" +... Class=MEDIA -ClassGuid= {4d36e96c-e325-11ce-bfc1-08002be10318} +ClassGuid={4d36e96c-e325-11ce-bfc1-08002be10318} ... [USBAudio] @@ -49,9 +51,9 @@ The following INF file snippet shows how an undefined output device (KSNODETYPE\ ```inf [Version] -Signature="$Windows NT$" +... Class=MEDIA -ClassGuid= {4d36e96c-e325-11ce-bfc1-08002be10318} +ClassGuid={4d36e96c-e325-11ce-bfc1-08002be10318} ... [USBAudio] @@ -111,14 +113,3 @@ In the preceding example, 0x00000305 is the bitwise OR combination of all the fl - - - - - - - - - - - diff --git a/windows-driver-docs-pr/audio/pkey-audioendpoint-default-volumeindb.md b/windows-driver-docs-pr/audio/pkey-audioendpoint-default-volumeindb.md index 0f01223ac1..fccb1f264b 100644 --- a/windows-driver-docs-pr/audio/pkey-audioendpoint-default-volumeindb.md +++ b/windows-driver-docs-pr/audio/pkey-audioendpoint-default-volumeindb.md @@ -1,9 +1,11 @@ --- title: PKEY\_AudioEndpoint\_Default\_VolumeInDb description: In Windows 10 Version 1605 and later, the PKEY\_AudioEndpoint\_Default\_VolumeInDb property key configures the default volume (in dB) for the software volume node. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # PKEY\_AudioEndpoint\_Default\_VolumeInDb @@ -41,7 +43,7 @@ HKR,EP\0,%PKEY_AudioEndpoint_Default_VolumeInDb%,0x00010001,0xA0000 ;HKR,EP\0,%PKEY_AudioEndpoint_Default_VolumeInDb%,0x00010001,0xFFF60000 ``` -## Related topics +## Related topics [Media-Class INF Extensions](media-class-inf-extensions.md) diff --git a/windows-driver-docs-pr/audio/pkey-audioengine-oemformat.md b/windows-driver-docs-pr/audio/pkey-audioengine-oemformat.md index 31f8984e58..bc0f59d0da 100644 --- a/windows-driver-docs-pr/audio/pkey-audioengine-oemformat.md +++ b/windows-driver-docs-pr/audio/pkey-audioengine-oemformat.md @@ -1,9 +1,11 @@ --- title: PKEY\_AudioEngine\_OEMFormat description: PKEY\_AudioEngine\_OEMFormat -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # PKEY\_AudioEngine\_OEMFormat diff --git a/windows-driver-docs-pr/audio/pkey-audioengine-oemperiod.md b/windows-driver-docs-pr/audio/pkey-audioengine-oemperiod.md index bb85d8f14d..9ee298f952 100644 --- a/windows-driver-docs-pr/audio/pkey-audioengine-oemperiod.md +++ b/windows-driver-docs-pr/audio/pkey-audioengine-oemperiod.md @@ -1,22 +1,27 @@ --- -title: PKEY\_AudioEngine\_OEMPeriod -description: PKEY\_AudioEngine\_OEMPeriod -ms.date: 11/28/2017 +title: PKEY_AudioEngine_OEMPeriod +description: PKEY_AudioEngine_OEMPeriod +ms.date: 05/05/2023 +ms.topic: reference --- -# PKEY\_AudioEngine\_OEMPeriod +# PKEY_AudioEngine_OEMPeriod - -The Windows audio engine runs at predetermined intervals that are referred to as the *periodicity* of the audio engine. In Windows 7 and later versions of Windows, the audio engine runs with a periodicity of 10ms by default. In Windows 7, you can use an INF file and a new registry key, **PKEY\_AudioEngine\_OEMPeriod**, to customize the periodicity for your audio device driver. This is a per endpoint setting. +The Windows audio engine runs at predetermined intervals that are referred to as the *periodicity* of the audio engine. In Windows 7 and later versions of Windows, the audio engine runs with a periodicity of 10 ms by default. In Windows 7, you can use an INF file and a new registry key, **PKEY_AudioEngine_OEMPeriod**, to customize the periodicity for your audio device driver. This is a per endpoint setting. The following excerpt from an INF file shows how to use the [**INF AddReg directive**](../install/inf-addreg-directive.md) to customize the periodicity for an audio device driver. ```inf [Version] -Signature="$CHICAGO$" +Signature="$Windows NT$" Class=MEDIA -Provider=%MSFT% +ClassGuid={4d36e96c-e325-11ce-bfc1-08002be10318} +Provider=%ExampleProvider% +CatalogFile=ExampleCatalog.cat +PnpLockdown=1 + ... + [USBAudio] Include=ks.inf, wdmaudio.inf, wdma_usb.inf Needs=KS.Registration, WDMAUDIO.Registration, USBAudio.CopyList, USBAudioOEM.AddReg @@ -40,18 +45,16 @@ 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] +ExampleProvider = "Example Provider" PKEY_AudioEndpoint_Association = "{1DA5D803-D492-4EDD-8C23-E0C0FFEE7F0E},2" PKEY_AudioEngine_OEMPeriod = "{E4870E26-3CC5-4CD2-BA46-CA0A9A70ED04},6" REG_BINARY = "0x00000001" ``` -Periodicity is specified as VT\_BLOB. And the valid periodicity range is 50000-90000 (5-9ms) on even 10000 HNSTIME unit boundaries (for example, 50000, 60000, 70000, 80000 or 90000). - -In the preceding excerpt from an INF file, the following REG\_BINARY data is provided for customization: - -The periodicity of 8ms is represented in HNSTIME units as 80000. In hexadecimal notation this value is represented as 0x013880. When this hexadecimal value is written four bits (nibbles) at a time, with least significant bits first, the result is 80,38,01. This is the value that is provided as a REG\_BINARY data type. +Periodicity is specified as VT_BLOB. And the valid periodicity range is 50000-90000 (5-9 ms) on even 10000 HNSTIME unit boundaries (for example, 50000, 60000, 70000, 80000 or 90000). -Periodicity is specified as a VT\_BLOB data type. This is represented by a decimal value of 65. In hexadecimal format 65 is represented by the value 41 and the preceding INF file excerpt shows the REG\_BINARY data sequence with its first value of 41. +In the preceding excerpt from an INF file, the following REG_BINARY data is provided for customization: - +The periodicity of 8 ms is represented in HNSTIME units as 80000. In hexadecimal notation this value is represented as 0x013880. When this hexadecimal value is written four bits (nibbles) at a time, with least significant bits first, the result is 80,38,01. This is the value that is provided as a REG_BINARY data type. +Periodicity is specified as a VT_BLOB data type. This is represented by a decimal value of 65. In hexadecimal format 65 is represented by the value 41 and the preceding INF file excerpt shows the REG_BINARY data sequence with its first value of 41. diff --git a/windows-driver-docs-pr/audio/pkey-compositefx-endpointeffectclsid.md b/windows-driver-docs-pr/audio/pkey-compositefx-endpointeffectclsid.md index c8e29252d1..c1f728475c 100644 --- a/windows-driver-docs-pr/audio/pkey-compositefx-endpointeffectclsid.md +++ b/windows-driver-docs-pr/audio/pkey-compositefx-endpointeffectclsid.md @@ -1,7 +1,8 @@ --- title: PKEY\_CompositeFX\_EndpointEffectClsid description: In Windows 10 Version 1803 and later, the PKEY\_CompositeFX\_EndpointEffectClsid property key identifies the end point effect (EFX) in place. -ms.date: 11/15/2018 +ms.date: 03/06/2023 +ms.topic: reference --- # PKEY\_CompositeFX\_EndpointEffectClsid @@ -31,7 +32,7 @@ HKR,FX\0,%PKEY_CompositeFX_EndpointEffectClsid%,0x00010000,%SWAP_FX_MODE_CLSID%, ``` -## Related topics +## Related topics [Media-Class INF Extensions](media-class-inf-extensions.md) diff --git a/windows-driver-docs-pr/audio/pkey-compositefx-keyworddetector-endpointeffectclsid.md b/windows-driver-docs-pr/audio/pkey-compositefx-keyworddetector-endpointeffectclsid.md index d624070c49..ab975f8152 100644 --- a/windows-driver-docs-pr/audio/pkey-compositefx-keyworddetector-endpointeffectclsid.md +++ b/windows-driver-docs-pr/audio/pkey-compositefx-keyworddetector-endpointeffectclsid.md @@ -1,7 +1,8 @@ --- title: PKEY\_CompositeFX\_KeywordDetector\_EndpointEffectClsid description: In Windows 10 version 1803 and later, the PKEY\_CompositeFX\_KeywordDetector\_EndpointEffectClsid property key identifies the keyword detector end point effect (EFX) in place. -ms.date: 11/15/2018 +ms.date: 03/06/2023 +ms.topic: reference --- # PKEY\_CompositeFX\_KeywordDetector\_EndpointEffectClsid @@ -30,7 +31,7 @@ HKR,FX\0,%PKEY_CompositeFX_KeywordDetector_EndpointEffectClsid%,0x00010000,%SWAP ``` -## Related topics +## Related topics [Media-Class INF Extensions](media-class-inf-extensions.md) diff --git a/windows-driver-docs-pr/audio/pkey-compositefx-keyworddetector-modeeffectclsid.md b/windows-driver-docs-pr/audio/pkey-compositefx-keyworddetector-modeeffectclsid.md index ec4dd0d01a..ac9a4262ad 100644 --- a/windows-driver-docs-pr/audio/pkey-compositefx-keyworddetector-modeeffectclsid.md +++ b/windows-driver-docs-pr/audio/pkey-compositefx-keyworddetector-modeeffectclsid.md @@ -1,7 +1,8 @@ --- title: PKEY\_CompositeFX\_KeywordDetector\_ModeEffectClsid description: In Windows 10 Version 1803 and later, the PKEY\_CompositeFX\_KeywordDetector\_ModeEffectClsid property key identifies the mode effect (MFX) supported by the driver for the keyword detector pin. -ms.date: 11/15/2018 +ms.date: 03/06/2023 +ms.topic: reference --- # PKEY\_CompositeFX\_KeywordDetector\_ModeEffectClsid @@ -30,7 +31,7 @@ HKR,FX\0,%PKEY_CompositeFX_KeywordDetector_ModeEffectClsid%,0x00010000,%SWAP_FX_ ``` -## Related topics +## Related topics [Media-Class INF Extensions](media-class-inf-extensions.md) diff --git a/windows-driver-docs-pr/audio/pkey-compositefx-keyworddetector-streameffectclsid.md b/windows-driver-docs-pr/audio/pkey-compositefx-keyworddetector-streameffectclsid.md index 85f79f0fd4..a1c6a1d26c 100644 --- a/windows-driver-docs-pr/audio/pkey-compositefx-keyworddetector-streameffectclsid.md +++ b/windows-driver-docs-pr/audio/pkey-compositefx-keyworddetector-streameffectclsid.md @@ -1,7 +1,8 @@ --- title: PKEY\_CompositeFX\_KeywordDetector\_StreamEffectClsid description: In Windows 10 Version 1803 and later, the PKEY\_CompositeFX\_KeywordDetector\_StreamEffectClsid property key identifies the stream effect (SFX) supported for the keyword detector by the driver. -ms.date: 11/15/2018 +ms.date: 03/06/2023 +ms.topic: reference --- # PKEY\_CompositeFX\_KeywordDetector\_StreamEffectClsid @@ -31,7 +32,7 @@ HKR,FX\0,%PKEY_CompositeFX_KeywordDetector_StreamEffectClsid%,0x00010000,%SWAP_F ``` -## Related topics +## Related topics [Media-Class INF Extensions](media-class-inf-extensions.md) diff --git a/windows-driver-docs-pr/audio/pkey-compositefx-modeeffectclsid.md b/windows-driver-docs-pr/audio/pkey-compositefx-modeeffectclsid.md index e61ac73ca9..523c2ffcbd 100644 --- a/windows-driver-docs-pr/audio/pkey-compositefx-modeeffectclsid.md +++ b/windows-driver-docs-pr/audio/pkey-compositefx-modeeffectclsid.md @@ -1,7 +1,8 @@ --- title: PKEY\_CompositeFX\_ModeEffectClsid description: In Windows 10 Version 1803 later, the PKEY\_Compositefx\_ModeEffectClsid property key identifies the mode effect (MFX) supported by the driver. The driver developer should specify the list of supported processing modes that their driver supports. -ms.date: 11/15/2018 +ms.date: 03/06/2023 +ms.topic: reference --- # PKEY\_CompositeFX\_ModeEffectClsid @@ -30,7 +31,7 @@ HKR,FX\0,%PKEY_CompositeFX_ModeEffectClsid%,0x00010000,%SWAP_FX_MODE_CLSID%,%DEL ``` -## Related topics +## Related topics [Media-Class INF Extensions](media-class-inf-extensions.md) diff --git a/windows-driver-docs-pr/audio/pkey-compositefx-offload-modeeffectclsid.md b/windows-driver-docs-pr/audio/pkey-compositefx-offload-modeeffectclsid.md index 20bf052721..afea254fc4 100644 --- a/windows-driver-docs-pr/audio/pkey-compositefx-offload-modeeffectclsid.md +++ b/windows-driver-docs-pr/audio/pkey-compositefx-offload-modeeffectclsid.md @@ -1,7 +1,8 @@ --- title: PKEY\_CompositeFX\_Offload\_ModeEffectClsid description: In Windows 10, version 1803 and later, the PKEY\_CompositeFX\_Offload\_ModeEffectClsid key identifies the mode effect (MFX) supported by the driver that will be loaded during offload playback. -ms.date: 11/15/2018 +ms.date: 03/06/2023 +ms.topic: reference --- # PKEY\_CompositeFX\_Offload\_ModeEffectClsid @@ -32,7 +33,7 @@ HKR,FX\0,%PKEY_CompositeFX_Offload_ModeEffectClsid%,0x00010000,%SWAP_FX_MODE_CLS ``` -## Related topics +## Related topics [Media-Class INF Extensions](media-class-inf-extensions.md) diff --git a/windows-driver-docs-pr/audio/pkey-compositefx-offload-streameffectclsid.md b/windows-driver-docs-pr/audio/pkey-compositefx-offload-streameffectclsid.md index f8b2e1136f..33fdad204d 100644 --- a/windows-driver-docs-pr/audio/pkey-compositefx-offload-streameffectclsid.md +++ b/windows-driver-docs-pr/audio/pkey-compositefx-offload-streameffectclsid.md @@ -1,7 +1,8 @@ --- title: PKEY\_CompositeFX\_Offload\_StreamEffectClsid description: In Windows 10, version 1803 and later, the PKEY\_CompositeFX\_Offload\_StreamEffectClsid property key identifies the stream effect (SFX) supported by the driver. -ms.date: 01/07/2020 +ms.date: 03/06/2023 +ms.topic: reference --- # PKEY\_CompositeFX\_Offload\_StreamEffectClsid @@ -31,6 +32,6 @@ HKR,FX\0,%PKEY_CompositeFX_Offload_StreamEffectClsid%,0x00010000,%SWAP_FX_MODE_C ``` -## Related topics +## Related topics [Media-Class INF Extensions](media-class-inf-extensions.md) diff --git a/windows-driver-docs-pr/audio/pkey-compositefx-streameffectclsid.md b/windows-driver-docs-pr/audio/pkey-compositefx-streameffectclsid.md index f9bc368b40..4083429007 100644 --- a/windows-driver-docs-pr/audio/pkey-compositefx-streameffectclsid.md +++ b/windows-driver-docs-pr/audio/pkey-compositefx-streameffectclsid.md @@ -1,7 +1,8 @@ --- title: PKEY\_CompositeFX\_StreamEffectClsid description: In Windows 10 version 1803 and later, the PKEY\_FX\_StreamEffectClsid property key identifies the stream effect (SCompositeFX) supported by the driver. The driver developer should specify the list of supported stream effects that their driver supports. -ms.date: 11/15/2018 +ms.date: 03/06/2023 +ms.topic: reference --- # PKEY\_CompositeFX\_StreamEffectClsid @@ -32,7 +33,7 @@ HKR,FX\0,%PKEY_CompositeFX_StreamEffectClsid%,0x00010000,%SWAP_FX_MODE_CLSID%,%D ``` -## Related topics +## Related topics [Media-Class INF Extensions](media-class-inf-extensions.md) diff --git a/windows-driver-docs-pr/audio/pkey-devices-audiodevice-microphone-isfarfield.md b/windows-driver-docs-pr/audio/pkey-devices-audiodevice-microphone-isfarfield.md index c0388900f1..7d485927aa 100644 --- a/windows-driver-docs-pr/audio/pkey-devices-audiodevice-microphone-isfarfield.md +++ b/windows-driver-docs-pr/audio/pkey-devices-audiodevice-microphone-isfarfield.md @@ -1,7 +1,8 @@ --- title: PKEY\_Devices\_AudioDevice\_Microphone\_IsFarField -description: In Windows 10 Version 19H1 and later, **PKEY\_Devices\_AudioDevice\_Microphone\_IsFarField** property key identifies indicates if the microphone will capture far field audio. -ms.date: 02/13/2019 +description: In Windows 10 Version 19H1 and later, **PKEY\_Devices\_AudioDevice\_Microphone\_IsFarField** property key identifies +ms.date: 03/08/2023 +ms.topic: reference --- # PKEY\_Devices\_AudioDevice\_Microphone\_IsFarField diff --git a/windows-driver-docs-pr/audio/pkey-efx-keyworddetector-processingmodes-supported-for-streaming.md b/windows-driver-docs-pr/audio/pkey-efx-keyworddetector-processingmodes-supported-for-streaming.md index db929c4a81..a08b332e22 100644 --- a/windows-driver-docs-pr/audio/pkey-efx-keyworddetector-processingmodes-supported-for-streaming.md +++ b/windows-driver-docs-pr/audio/pkey-efx-keyworddetector-processingmodes-supported-for-streaming.md @@ -1,9 +1,11 @@ --- title: PKEY\_EFX\_KeywordDetector\_ProcessingModes\_Supported\_For\_Streaming description: In Windows 10 and later, the PKEY\_EFX\_KeywordDetector\_ProcessingModes\_Supported\_For\_Streaming property key identifies the end point keyword detector processing modes supported for streaming supported by the driver. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # PKEY\_EFX\_KeywordDetector\_ProcessingModes\_Supported\_For\_Streaming @@ -29,7 +31,7 @@ PKEY_EFX_KeywordDetector_ProcessingModes_Supported_For_Streaming = "{D3993A3F-99 HKR,FX\0,%PKEY_EFX_KeywordDetector_ProcessingModes_Supported_For_Streaming%,0x00010000,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT% ``` -## Related topics +## Related topics [Media-Class INF Extensions](media-class-inf-extensions.md) diff --git a/windows-driver-docs-pr/audio/pkey-efx-processingmodes-supported-for-streaming.md b/windows-driver-docs-pr/audio/pkey-efx-processingmodes-supported-for-streaming.md index 3983f64060..2adfcdf140 100644 --- a/windows-driver-docs-pr/audio/pkey-efx-processingmodes-supported-for-streaming.md +++ b/windows-driver-docs-pr/audio/pkey-efx-processingmodes-supported-for-streaming.md @@ -1,9 +1,11 @@ --- title: PKEY\_EFX\_ProcessingModes\_Supported\_For\_Streaming description: In Windows 8.1 and later, the PKEY\_EFX\_ProcessingModes\_Supported\_For\_Streaming property key identifies the end point processing modes supported for streaming supported by the driver. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # PKEY\_EFX\_ProcessingModes\_Supported\_For\_Streaming @@ -27,7 +29,7 @@ PKEY_EFX_ProcessingModes_Supported_For_Streaming = "{D3993A3F-99C2-4402-B5EC-A92 HKR,FX\0,%PKEY_EFX_ProcessingModes_Supported_For_Streaming%,0x00010000,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT% ``` -## Related topics +## Related topics [Media-Class INF Extensions](media-class-inf-extensions.md) diff --git a/windows-driver-docs-pr/audio/pkey-fx-endpointeffectclsid.md b/windows-driver-docs-pr/audio/pkey-fx-endpointeffectclsid.md index c4473436bc..a9a7224240 100644 --- a/windows-driver-docs-pr/audio/pkey-fx-endpointeffectclsid.md +++ b/windows-driver-docs-pr/audio/pkey-fx-endpointeffectclsid.md @@ -1,9 +1,11 @@ --- title: PKEY\_FX\_EndpointEffectClsid description: In Windows 8.1 and later, the PKEY\_FX\_EndpointEffectClsid property key identifies the end point effect (EFX) in place. The driver developer should specify the list of supported processing modes that their driver supports. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # PKEY\_FX\_EndpointEffectClsid @@ -27,7 +29,7 @@ FX_ENDPOINT_CLSID = "{00000000-0000-0000-0000-000000000000}" HKR,"FX\\0",%PKEY_FX_EndpointEffectClsid%,,%FX_ENDPOINT_CLSID% ``` -## Related topics +## Related topics [Media-Class INF Extensions](media-class-inf-extensions.md) diff --git a/windows-driver-docs-pr/audio/pkey-fx-keyworddetector-endpointeffectclsid.md b/windows-driver-docs-pr/audio/pkey-fx-keyworddetector-endpointeffectclsid.md index 729984ab26..940fc59c31 100644 --- a/windows-driver-docs-pr/audio/pkey-fx-keyworddetector-endpointeffectclsid.md +++ b/windows-driver-docs-pr/audio/pkey-fx-keyworddetector-endpointeffectclsid.md @@ -1,9 +1,11 @@ --- title: PKEY\_FX\_KeywordDetector\_EndpointEffectClsid description: In Windows 10 and later, the PKEY\_FX\_KeywordDetector\_EndpointEffectClsid property key identifies the keyword detector end point effect (EFX) in place. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # PKEY\_FX\_KeywordDetector\_EndpointEffectClsid @@ -27,7 +29,7 @@ FX_KEYWORD_ENDPOINT_CLSID = "{00000000-0000-0000-0000-000000000000 HKR,"FX\\0",%PKEY_FX_KeywordDetector_EndpointEffectClsid%,,%FX_KEYWORD_ENDPOINT_CLSID% ``` -## Related topics +## Related topics [Media-Class INF Extensions](media-class-inf-extensions.md) diff --git a/windows-driver-docs-pr/audio/pkey-fx-keyworddetector-modeeffectclsid.md b/windows-driver-docs-pr/audio/pkey-fx-keyworddetector-modeeffectclsid.md index a1c098ec89..511e952b0c 100644 --- a/windows-driver-docs-pr/audio/pkey-fx-keyworddetector-modeeffectclsid.md +++ b/windows-driver-docs-pr/audio/pkey-fx-keyworddetector-modeeffectclsid.md @@ -1,9 +1,11 @@ --- title: PKEY\_FX\_KeywordDetector\_ModeEffectClsid description: In Windows 10 and later, the PKEY\_FX\_KeywordDetector\_ModeEffectClsid property key identifies the mode effect (MFX) supported by the driver for the keyword detector pin. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # PKEY\_FX\_KeywordDetector\_ModeEffectClsid @@ -27,7 +29,7 @@ FX_KEYWORD_MODE_CLSID = "{00000000-0000-0000-0000-000000000000}" HKR,"FX\\0",%PKEY_FX_KeywordDetector_ModeEffectClsid%,,%FX_KEYWORD_MODE_CLSID% ``` -## Related topics +## Related topics [Media-Class INF Extensions](media-class-inf-extensions.md) diff --git a/windows-driver-docs-pr/audio/pkey-fx-keyworddetector-streameffectclsid.md b/windows-driver-docs-pr/audio/pkey-fx-keyworddetector-streameffectclsid.md index 8f36291b78..3b535fb57a 100644 --- a/windows-driver-docs-pr/audio/pkey-fx-keyworddetector-streameffectclsid.md +++ b/windows-driver-docs-pr/audio/pkey-fx-keyworddetector-streameffectclsid.md @@ -1,9 +1,11 @@ --- title: PKEY\_FX\_KeywordDetector\_StreamEffectClsid description: In Windows 10 and later, the PKEY\_FX\_KeywordDetector\_StreamEffectClsid property key identifies the stream effect (SFX) supported for the keyword detector by the driver. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # PKEY\_FX\_KeywordDetector\_StreamEffectClsid @@ -27,7 +29,7 @@ FX_KEYWORD_STREAM_CLSID = "{00000000-0000-0000-0000-000000000000}" HKR,"FX\\0",%PKEY_FX_KeywordDetector_StreamEffectClsid%,,%FX_KEYWORD_STREAM_CLSID% ``` -## Related topics +## Related topics [Media-Class INF Extensions](media-class-inf-extensions.md) diff --git a/windows-driver-docs-pr/audio/pkey-fx-modeeffectclsid.md b/windows-driver-docs-pr/audio/pkey-fx-modeeffectclsid.md index 3e13671418..d68b45572e 100644 --- a/windows-driver-docs-pr/audio/pkey-fx-modeeffectclsid.md +++ b/windows-driver-docs-pr/audio/pkey-fx-modeeffectclsid.md @@ -1,9 +1,11 @@ --- title: PKEY\_FX\_ModeEffectClsid description: In Windows 8.1 and later, the PKEY\_FX\_ModeEffectClsid property key identifies the mode effect (MFX) supported by the driver. The driver developer should specify the list of supported processing modes that their driver supports. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # PKEY\_FX\_ModeEffectClsid @@ -27,7 +29,7 @@ FX_MODE_CLSID = "{00000000-0000-0000-0000-000000000000}" HKR,"FX\\0",%PKEY_FX_ModeEffectClsid%,,%FX_MODE_CLSID% ``` -## Related topics +## Related topics [Media-Class INF Extensions](media-class-inf-extensions.md) diff --git a/windows-driver-docs-pr/audio/pkey-fx-offload-modeeffectclsid.md b/windows-driver-docs-pr/audio/pkey-fx-offload-modeeffectclsid.md index 8dd8e064d7..60d168295f 100644 --- a/windows-driver-docs-pr/audio/pkey-fx-offload-modeeffectclsid.md +++ b/windows-driver-docs-pr/audio/pkey-fx-offload-modeeffectclsid.md @@ -1,9 +1,11 @@ --- title: PKEY\_FX\_Offload\_ModeEffectClsid description: In Windows 10, version 1511 and later, the PKEY\_FX\_Offload\_ModeEffectClsid key identifies the mode effect (MFX) supported by the driver that will be loaded during offload playback. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # PKEY\_FX\_Offload\_ModeEffectClsid @@ -27,7 +29,7 @@ FX_MODE_CLSID = "{00000000-0000-0000-0000-000000000000}" HKR,"FX\\0",%PKEY_FX_Offload_ModeEffectClsid%,,%FX_MODE_CLSID% ``` -## Related topics +## Related topics [Media-Class INF Extensions](media-class-inf-extensions.md) diff --git a/windows-driver-docs-pr/audio/pkey-fx-offload-streameffectclsid.md b/windows-driver-docs-pr/audio/pkey-fx-offload-streameffectclsid.md index b10cd13e51..f6939462d4 100644 --- a/windows-driver-docs-pr/audio/pkey-fx-offload-streameffectclsid.md +++ b/windows-driver-docs-pr/audio/pkey-fx-offload-streameffectclsid.md @@ -1,9 +1,11 @@ --- title: PKEY\_FX\_Offload\_StreamEffectClsid description: In Windows 10, version 1511 and later, the PKEY\_FX\_Offload\_StreamEffectClsid property key identifies the stream effect (SFX) supported by the driver that will be loaded during offload playback. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # PKEY\_FX\_Offload\_StreamEffectClsid @@ -27,7 +29,7 @@ FX_STREAM_CLSID = "{00000000-0000-0000-0000-000000000000}" HKR,"FX\\0",% PKEY_FX_Offload_StreamEffectClsid %,,%FX_STREAM_CLSID% ``` -## Related topics +## Related topics [Media-Class INF Extensions](media-class-inf-extensions.md) diff --git a/windows-driver-docs-pr/audio/pkey-fx-streameffectclsid.md b/windows-driver-docs-pr/audio/pkey-fx-streameffectclsid.md index a96bdee116..970606fe78 100644 --- a/windows-driver-docs-pr/audio/pkey-fx-streameffectclsid.md +++ b/windows-driver-docs-pr/audio/pkey-fx-streameffectclsid.md @@ -1,9 +1,11 @@ --- title: PKEY\_FX\_StreamEffectClsid description: In Windows 8.1 and later, the PKEY\_FX\_StreamEffectClsid property key identifies the stream effect (SFX) supported by the driver. The driver developer should specify the list of supported stream effects that their driver supports. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # PKEY\_FX\_StreamEffectClsid @@ -27,7 +29,7 @@ FX_STREAM_CLSID = "{00000000-0000-0000-0000-000000000000}" HKR,"FX\\0",%PKEY_FX_StreamEffectClsid%,,%FX_STREAM_CLSID% ``` -## Related topics +## Related topics [Media-Class INF Extensions](media-class-inf-extensions.md) diff --git a/windows-driver-docs-pr/audio/pkey-mfx-keyworddetector-processingmodes-supported-for-streaming.md b/windows-driver-docs-pr/audio/pkey-mfx-keyworddetector-processingmodes-supported-for-streaming.md index b75264af99..d5507eeefa 100644 --- a/windows-driver-docs-pr/audio/pkey-mfx-keyworddetector-processingmodes-supported-for-streaming.md +++ b/windows-driver-docs-pr/audio/pkey-mfx-keyworddetector-processingmodes-supported-for-streaming.md @@ -1,9 +1,11 @@ --- title: PKEY\_MFX\_KeywordDetector\_ProcessingModes\_Supported\_For\_Streaming description: In Windows 10 and later, the PKEY\_MFX\_KeywordDetector\_ProcessingModes\_Supported\_For\_Streaming property key identifies the keyword detector mode effect processing modes supported for streaming supported by the driver. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # PKEY\_MFX\_KeywordDetector\_ProcessingModes\_Supported\_For\_Streaming @@ -31,7 +33,7 @@ AUDIO_SIGNALPROCESSINGMODE_COMMUNICATIONS = "{98951333-B9CD-48B1-A0A3-FF40682D73 HKR,"FX\\0",%PKEY_MFX_KeywordDetector_ProcessingModes_Supported_For_Streaming%,%REG_MULTI_SZ%,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT%,%AUDIO_SIGNALPROCESSINGMODE_MOVIE%,%AUDIO_SIGNALPROCESSINGMODE_COMMUNICATIONS% ``` -## Related topics +## Related topics [Media-Class INF Extensions](media-class-inf-extensions.md) diff --git a/windows-driver-docs-pr/audio/pkey-mfx-offload-processingmodes-supported-for-streaming.md b/windows-driver-docs-pr/audio/pkey-mfx-offload-processingmodes-supported-for-streaming.md index 2a67be036a..575fac8204 100644 --- a/windows-driver-docs-pr/audio/pkey-mfx-offload-processingmodes-supported-for-streaming.md +++ b/windows-driver-docs-pr/audio/pkey-mfx-offload-processingmodes-supported-for-streaming.md @@ -1,9 +1,11 @@ --- title: PKEY\_MFX\_Offload\_ProcessingModes\_Supported\_For\_Streaming description: In Windows 10, version 1511 and later, the PKEY\_MFX\_Offload\_ProcessingModes\_Supported\_For\_Streaming property key identifies the mode effect processing modes supported for offload streaming supported by the driver. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # PKEY\_MFX\_Offload\_ProcessingModes\_Supported\_For\_Streaming @@ -30,7 +32,7 @@ AUDIO_SIGNALPROCESSINGMODE_MEDIA = "{4780004E-7133-41D8-8C74-660DADD2C0EE}" HKR,"FX\\0",%PKEY_MFX_Offload_ProcessingModes_For_Streaming%,%REG_MULTI_SZ%,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT%,%AUDIO_SIGNALPROCESSINGMODE_MOVIE%,%AUDIO_SIGNALPROCESSINGMODE_MEDIA% ``` -## Related topics +## Related topics [Media-Class INF Extensions](media-class-inf-extensions.md) diff --git a/windows-driver-docs-pr/audio/pkey-mfx-processingmodes-supported-for-streaming.md b/windows-driver-docs-pr/audio/pkey-mfx-processingmodes-supported-for-streaming.md index 3d9aabdd4c..d5f4e4d324 100644 --- a/windows-driver-docs-pr/audio/pkey-mfx-processingmodes-supported-for-streaming.md +++ b/windows-driver-docs-pr/audio/pkey-mfx-processingmodes-supported-for-streaming.md @@ -1,9 +1,11 @@ --- title: PKEY\_MFX\_ProcessingModes\_Supported\_For\_Streaming description: In Windows 8.1 and later, the PKEY\_MFX\_ProcessingModes\_Supported\_For\_Streaming property key identifies the mode effect processing modes supported for streaming supported by the driver. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # PKEY\_MFX\_ProcessingModes\_Supported\_For\_Streaming @@ -29,7 +31,7 @@ AUDIO_SIGNALPROCESSINGMODE_COMMUNICATIONS = "{98951333-B9CD-48B1-A0A3-FF40682D73 HKR,"FX\\0",%PKEY_MFX_ProcessingModes_For_Streaming%,%REG_MULTI_SZ%,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT%,%AUDIO_SIGNALPROCESSINGMODE_MOVIE%,%AUDIO_SIGNALPROCESSINGMODE_COMMUNICATIONS% ``` -## Related topics +## Related topics [Media-Class INF Extensions](media-class-inf-extensions.md) diff --git a/windows-driver-docs-pr/audio/pkey-sfx-keyworddetector-processingmodes-supported-for-streaming.md b/windows-driver-docs-pr/audio/pkey-sfx-keyworddetector-processingmodes-supported-for-streaming.md index b7ecff148f..30db22bb07 100644 --- a/windows-driver-docs-pr/audio/pkey-sfx-keyworddetector-processingmodes-supported-for-streaming.md +++ b/windows-driver-docs-pr/audio/pkey-sfx-keyworddetector-processingmodes-supported-for-streaming.md @@ -1,9 +1,11 @@ --- title: PKEY\_SFX\_KeywordDetector\_ProcessingModes\_Supported\_For\_Streaming description: In Windows 10 and later, the PKEY\_SFX\_KeywordDetector\_ProcessingModes\_Supported\_For\_Streaming property key identifies the keyword detector streaming processing modes supported by the driver. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # PKEY\_SFX\_KeywordDetector\_ProcessingModes\_Supported\_For\_Streaming @@ -31,7 +33,7 @@ AUDIO_SIGNALPROCESSINGMODE_COMMUNICATIONS = "{98951333-B9CD-48B1-A0A3-FF40682D73 HKR,"FX\\0",%PKEY_SFX_KeywordDetector_ProcessingModes_Supported_For_Streaming%,%REG_MULTI_SZ%,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT%,%AUDIO_SIGNALPROCESSINGMODE_MOVIE%,%AUDIO_SIGNALPROCESSINGMODE_COMMUNICATIONS% ``` -## Related topics +## Related topics [Media-Class INF Extensions](media-class-inf-extensions.md) diff --git a/windows-driver-docs-pr/audio/pkey-sfx-offload-processingmodes-supported-for-streaming.md b/windows-driver-docs-pr/audio/pkey-sfx-offload-processingmodes-supported-for-streaming.md index 09d84e5f40..34dcaf9ab8 100644 --- a/windows-driver-docs-pr/audio/pkey-sfx-offload-processingmodes-supported-for-streaming.md +++ b/windows-driver-docs-pr/audio/pkey-sfx-offload-processingmodes-supported-for-streaming.md @@ -1,9 +1,11 @@ --- title: PKEY\_SFX\_Offload\_ProcessingModes\_Supported\_For\_Streaming description: In Windows 10, version 1511 and later, the PKEY\_SFX\_Offload\_ProcessingModes\_Supported\_For\_Streaming property key identifies the offload streaming processing modes supported by the driver. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # PKEY\_SFX\_Offload\_ProcessingModes\_Supported\_For\_Streaming @@ -31,7 +33,7 @@ AUDIO_SIGNALPROCESSINGMODE_MEDIA = "{4780004E-7133-41D8-8C74-660DADD2C0EE}" HKR,"FX\\0",%PKEY_SFX_Offload_ProcessingModes_Supported_For_Streaming%,%REG_MULTI_SZ%,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT%,%AUDIO_SIGNALPROCESSINGMODE_MOVIE%,%AUDIO_SIGNALPROCESSINGMODE_MEDIA% ``` -## Related topics +## Related topics [Media-Class INF Extensions](media-class-inf-extensions.md) diff --git a/windows-driver-docs-pr/audio/pkey-sfx-processingmodes-supported-for-streaming.md b/windows-driver-docs-pr/audio/pkey-sfx-processingmodes-supported-for-streaming.md index 85563a93bd..6db32dc5d5 100644 --- a/windows-driver-docs-pr/audio/pkey-sfx-processingmodes-supported-for-streaming.md +++ b/windows-driver-docs-pr/audio/pkey-sfx-processingmodes-supported-for-streaming.md @@ -1,9 +1,11 @@ --- title: PKEY\_SFX\_ProcessingModes\_Supported\_For\_Streaming description: In Windows 8.1 and later, the PKEY\_SFX\_ProcessingModes\_Supported\_For\_Streaming property key identifies the streaming processing modes supported by the driver. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # PKEY\_SFX\_ProcessingModes\_Supported\_For\_Streaming @@ -29,7 +31,7 @@ AUDIO_SIGNALPROCESSINGMODE_COMMUNICATIONS = "{98951333-B9CD-48B1-A0A3-FF40682D73 HKR,"FX\\0",%PKEY_SFX_ProcessingModes_For_Streaming%,%REG_MULTI_SZ%,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT%,%AUDIO_SIGNALPROCESSINGMODE_MOVIE%,%AUDIO_SIGNALPROCESSINGMODE_COMMUNICATIONS% ``` -## Related topics +## Related topics [Media-Class INF Extensions](media-class-inf-extensions.md) diff --git a/windows-driver-docs-pr/audio/port-class-audio-driver-reference.md b/windows-driver-docs-pr/audio/port-class-audio-driver-reference.md index 594c370d88..608404230c 100644 --- a/windows-driver-docs-pr/audio/port-class-audio-driver-reference.md +++ b/windows-driver-docs-pr/audio/port-class-audio-driver-reference.md @@ -1,9 +1,11 @@ --- title: Port Class Audio Driver Reference description: Port Class Audio Driver Reference -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # Port Class Audio Driver Reference diff --git a/windows-driver-docs-pr/audio/portal-audio-ref.md b/windows-driver-docs-pr/audio/portal-audio-ref.md index 42a13d1b2f..7267205d93 100644 --- a/windows-driver-docs-pr/audio/portal-audio-ref.md +++ b/windows-driver-docs-pr/audio/portal-audio-ref.md @@ -1,9 +1,11 @@ --- title: Audio Devices DDI Reference description: This section contains the reference pages for audio drivers that conform to the Windows Driver Model (WDM) and reference pages for interfaces for audio processing objects. -ms.date: 11/28/2017 +ms.date: 03/06/2023 +ms.topic: reference --- + # Audio Devices DDI Reference diff --git a/windows-driver-docs-pr/audio/portcls-private-pep-context-sharing.md b/windows-driver-docs-pr/audio/portcls-private-pep-context-sharing.md index fe5bb8949a..c6b225f190 100644 --- a/windows-driver-docs-pr/audio/portcls-private-pep-context-sharing.md +++ b/windows-driver-docs-pr/audio/portcls-private-pep-context-sharing.md @@ -6,13 +6,11 @@ ms.date: 04/20/2017 # PortCls Private PEP Context Sharing - Starting with Windows 8, a miniport driver can use IPortClsRuntimePower, a new interface, for private context sharing with the Windows Power Engine Plug-in (PEP). The audio port class driver (PortCls) has been updated to expose the new interface, IPortClsRuntimePower, on the WaveRT port. In order for a miniport driver to send private power controls to the operating system's PEP, the miniport driver first has to gain access to the IPortClsRuntimePower interface of its associated port. The miniport driver then registers a callback that is invoked at the appropriate time, allowing the miniport driver to send the private power controls. -## Accessing IPortClsRuntimePower - +## Accessing IPortClsRuntimePower The miniport driver gains access to its port's IPortClsRuntimePower via the following sequence of events: @@ -32,14 +30,13 @@ DEFINE_GUID(IID_IPortClsRuntimePower, 0xe057c351, 0x430, 0x4dbc, 0xb1, 0x72, 0xc7, 0x11, 0xd4, 0xa, 0x23, 0x73); ``` -## Registering a callback - +## Registering a callback The miniport driver uses the [**IPortClsRuntimePower::RegisterPowerControlCallback**](/windows-hardware/drivers/ddi/portcls/nf-portcls-iportclsruntimepower-registerpowercontrolcallback) method to register a callback. This method is invoked either when the PEP initiates a private request, or in response to a private request that is initiated by the miniport driver itself. The callback registration should typically be performed while the driver is handling the IRP\_MN\_START\_DEVICE PNP Irp. Aside from the Context pointer that is supplied in the callback, the other parameters are defined identically to the definitions for the runtime power framework’s PowerControlCallback. Additionally, the miniport’s callback must be of type PCPFNRUNTIME\_POWER\_CONTROL\_CALLBACK, as defined in the following snippet from the *Portcls.h* header file. -```ManagedCPlusPlus +```cpp typedef NTSTATUS _IRQL_requires_max_(DISPATCH_LEVEL) @@ -57,12 +54,8 @@ _IRQL_requires_max_(DISPATCH_LEVEL) When the driver is stopped or removed, it must use the [**IPortClsRuntimePower::UnregisterPowerControlCallback**](/windows-hardware/drivers/ddi/portcls/nf-portcls-iportclsruntimepower-unregisterpowercontrolcallback) method to unregister any registered callbacks. -## Sending private power controls - +## Sending private power controls After the miniport establishes access to an **IPortClsRuntimePower** interface, and uses the interface's **RegisterPowerControlCallback** method to register a callback, it is now ready to send private power controls. When the callback method is invoked, the miniport driver uses the [**IPortClsRuntimePower::SendPowerControl**](/windows-hardware/drivers/ddi/portcls/nf-portcls-iportclsruntimepower-sendpowercontrol) method to send the private power controls to the Windows PEP. With the exception of the *DeviceObject* parameter, all other parameters are defined identically to those for the runtime power framework’s [PoFxPowerControl](/windows-hardware/drivers/ddi/wdm/nf-wdm-pofxpowercontrol) method. - - - diff --git a/windows-driver-docs-pr/audio/portcls-registry-power-settings.md b/windows-driver-docs-pr/audio/portcls-registry-power-settings.md index fff4f7d28f..cb53d83937 100644 --- a/windows-driver-docs-pr/audio/portcls-registry-power-settings.md +++ b/windows-driver-docs-pr/audio/portcls-registry-power-settings.md @@ -1,21 +1,21 @@ --- title: PortCls Registry Power Settings -description: This topic explains the PortCls registry power settings for Windows 8. -ms.date: 04/20/2017 +description: This topic explains the PortCls registry power settings for Windows. +ms.date: 09/29/2022 --- # PortCls Registry Power Settings -This topic explains the PortCls registry power settings for Windows 8. +This topic explains the PortCls registry power settings. -In Windows 8, (PortCls) miniport drivers can use registry values in the driver’s registry key to do the following: +In Windows, (PortCls) miniport drivers can use registry values in the driver’s registry key to do the following: - Determine whether or not PortCls enables idle power management - Determine the idle timeout values for battery conservation mode, versus high performance mode -By default, Windows 8 has power settings that PortCls uses to determine whether to register for "device idle" detection with the power manager, when the runtime power framework indicates that power is no longer required. The parameters that are used to describe the power setting profile are defined as follows. +By default, Windows has power settings that PortCls uses to determine whether to register for "device idle" detection with the power manager, when the runtime power framework indicates that power is no longer required. The parameters that are used to describe the power setting profile are defined as follows. @@ -62,11 +62,14 @@ By default, Windows 8 has power settings that PortCls uses to determine whether The following Windows registry fragment shows the syntax that is used for providing the power setting information. -``` syntax -[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Class\{4D36E96C-E325-11CE-BFC1-08002BE10318}\0000\PowerSettings] -"ConservationIdleTime"=hex:1e,00,00,00 -"PerformanceIdleTime"=hex:00,00,00,00 -"IdlePowerState"=hex:03,00,00,00 +```inf +[MyAudioDevice.AddReg] +HKR,PowerSettings,ConservationIdleTime,%REG_BINARY%, 0x1e, 0x00, 0x00, 0x00 +HKR,PowerSettings,PerformanceIdleTime,%REG_BINARY%, 0x00, 0x00, 0x00, 0x00 +HKR,PowerSettings,IdlePowerState,%REG_BINARY%, 0x03, 0x00, 0x00, 0x00 ``` The preceding fragment shows a hexadecimal (hex) value of "1e" for the *ConservationIdleTime*, and this equates to a 30-second idle timeout. The hex value of "0" shown for *PerformanceIdleTime* means that idle management has been disabled. And the value of "03" shown for the *IdlePowerState* means that when power is no longer needed, the device associated with this power setting profile will enter the D3 power state. + + + diff --git a/windows-driver-docs-pr/audio/related-design-guidelines.md b/windows-driver-docs-pr/audio/related-design-guidelines.md deleted file mode 100644 index 33b9155772..0000000000 --- a/windows-driver-docs-pr/audio/related-design-guidelines.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Related Design Guidelines -description: This topic describes how a port class audio driver and the driver for a Bluetooth Hands-free device can set device-related values and register APOs. -ms.date: 04/20/2017 ---- - -# Related Design Guidelines - - -The topics in the Related Design Guidelines section show how a port class audio driver and the audio driver for a Bluetooth Hands-free device can set device-related values and register audio processing objects. - -This section contains the following topics. - -[Setting Properties and Registry Values](setting-properties-and-registry-values.md) - -[Setting Friendly Names, Registering APOs](setting-friendly-name--registering-apos.md) - -[Obtaining Bluetooth Address of HF Device](obtaining-bluetooth-address-of-hf-device.md) - - - - - - - - diff --git a/windows-driver-docs-pr/audio/removal.md b/windows-driver-docs-pr/audio/removal.md index 9266bc6922..f73ebe78f9 100644 --- a/windows-driver-docs-pr/audio/removal.md +++ b/windows-driver-docs-pr/audio/removal.md @@ -1,28 +1,22 @@ --- -title: HFP Device Removal -description: The HFP device removal topic discusses what happens when a Bluetooth hands-free profile (HFP) device is removed from (leaves) the audio system. -ms.date: 04/20/2017 +title: HFP device removal +description: Learn about the process and consequences of removing a Bluetooth hands-free profile (HFP) device from an audio system. +ms.date: 07/27/2023 --- -# HFP Device Removal +# HFP device removal +This article discusses what how the audio driver should respond when when a Bluetooth hands-free profile (HFP) device is removed from (leaves) the audio system. -The HFP device removal topic discusses what happens when a Bluetooth hands-free profile (HFP) device is removed from (leaves) the audio system. - -To remove the registered device interface for a paired HFP device, the audio driver: - -1. Cancels any pending IOCTL\_BTHHFP\_SPEAKER\_GET\_VOLUME\_STATUS\_UPDATE IOCTLs. - -2. Cancels any pending IOCTL\_BTHHFP\_STREAM\_GET\_STATUS\_UPDATE IOCTLs. - -3. Cancels any pending IOCTL\_BTHHFP\_DEVICE\_GET\_CONNECTION\_STATUS\_UPDATE IOCTLs. - -4. De-references the HFP FileObject (which also de-references the DeviceObject). - -5. Calls KsDeleteFilterFactory to remove the filter factory that represents the HFP device associated with the removed interface. - -## Related topics -[Theory of Operation](theory-of-operation.md) +To remove the registered device interface for a paired HFP device, follow these steps: +1. Cancel any pending IOCTL_BTHHFP_SPEAKER_GET_VOLUME_STATUS_UPDATE IOCTLs. +2. Cancel any pending IOCTL_BTHHFP_STREAM_GET_STATUS_UPDATE IOCTLs. +3. Cancel any pending IOCTL_BTHHFP_DEVICE_GET_CONNECTION_STATUS_UPDATE IOCTLs. +4. De-reference the HFP FileObject (which also de-references the DeviceObject). +5. Select KsDeleteFilterFactory to remove the filter factory representing the HFP device associated with the removed interface. +## Related topics +- [Bluetooth HFP bypass audio streaming](bluetooth-hfp-bypass-audio-streaming.md) +- [Bluetooth Low Energy (LE) Audio](../bluetooth/bluetooth-low-energy-audio.md) diff --git a/windows-driver-docs-pr/audio/sample-audio-drivers.md b/windows-driver-docs-pr/audio/sample-audio-drivers.md index dbe8f1bb0b..3c96ed0217 100644 --- a/windows-driver-docs-pr/audio/sample-audio-drivers.md +++ b/windows-driver-docs-pr/audio/sample-audio-drivers.md @@ -51,7 +51,7 @@ The SYSVAD audio sample is available on the [Windows Driver Samples GitHub](http You can browse the Sysvad audio sample here: - + Follow these steps to download and open the SYSVAD sample. diff --git a/windows-driver-docs-pr/audio/setting-friendly-name--registering-apos.md b/windows-driver-docs-pr/audio/setting-friendly-name--registering-apos.md index 4e30bccb60..57637daed9 100644 --- a/windows-driver-docs-pr/audio/setting-friendly-name--registering-apos.md +++ b/windows-driver-docs-pr/audio/setting-friendly-name--registering-apos.md @@ -1,41 +1,44 @@ --- -title: Setting Friendly Names, Registering APOs +title: Setting Friendly Names, Sideband SCO Transport and Registering APOs description: This topic describes how a Port Class Bluetooth sideband audio driver can set the friendly name for a device interface, and register any APO that is used by the Bluetooth device. -ms.date: 04/20/2017 +ms.date: 10/05/2022 --- -# Setting Friendly Names, Registering APOs +# Setting Friendly Names, Sideband SCO Transport, and Registering APOs +The Setting Friendly Names, Sideband SCO Transport, and Registering APOs topic describes how a Port Class Bluetooth sideband audio driver can set the friendly name for a device interface, identify itself as having sideband SCO transport, and register any audio processing object (APO) that is used by the Bluetooth device. -The Setting Friendly Names, Registering APOs topic describes how a Port Class Bluetooth sideband audio driver can set the friendly name for a device interface, and register any audio processing object (APO) that is used by the Bluetooth device. +For each enabled GUID_DEVINTERFACE_BLUETOOTH_HFP_SCO_HCIBYPASS interface, the Port Class audio driver (PortCls) normally calls the PcRegisterSubdevice function, which registers PnP device interfaces that represent a sub-device on an audio adapter. In typical audio driver designs, the audio driver calls PcRegisterSubdevice for "wave" and "topology" sub-devices, which are then connected by calling other Port Class functions. -For each enabled GUID\_DEVINTERFACE\_BLUETOOTH\_HFP\_SCO\_HCIBYPASS interface, the Port Class audio driver (PortCls) normally calls the PcRegisterSubdevice function, which registers PnP device interfaces that represent a sub-device on an audio adapter. In typical audio driver designs, the audio driver calls PcRegisterSubdevice for “wave” and “topology” sub-devices, which are then connected by calling other Port Class functions. +Before calling PcRegisterSubdevice for the "topology" sub-device, the driver follows the procedure described in [Setting Properties and Registry Values](setting-properties-and-registry-values.md) to set properties and registry values on the interface in the KSCATEGORY_AUDIO interface class. The specific properties and registry values are described in the following sections. -Before calling PcRegisterSubdevice for the “topology” sub-device, the driver follows the procedure described in [Setting Properties and Registry Values](setting-properties-and-registry-values.md) to set properties and registry values on the interface in the KSCATEGORY\_AUDIO interface class. The specific properties and registry values are described in the following sections. +## DEVPKEY_DeviceInterface_FriendlyName -## DEVPKEY\_DeviceInterface\_FriendlyName - - -The audio driver sends an [**IOCTL\_BTHHFP\_DEVICE\_GET\_DESCRIPTOR**](/windows-hardware/drivers/ddi/bthhfpddi/ni-bthhfpddi-ioctl_bthhfp_device_get_descriptor) request to the Hands-free profile (HFP) audio driver. The requested information is returned in the form of a [**BTHHFP\_DESCRIPTOR**](/windows-hardware/drivers/ddi/bthhfpddi/ns-bthhfpddi-_bthhfp_descriptor) structure, plus an other data referenced by the structure. The audio driver then calls IoSetDeviceInterfacePropertyData to set DEVPKEY\_DeviceInterface\_FriendlyName to the value in the *FriendlyName* field of the **BTHHFP\_DESCRIPTOR** structure. +The audio driver sends an [**IOCTL_BTHHFP_DEVICE_GET_DESCRIPTOR**](/windows-hardware/drivers/ddi/bthhfpddi/ni-bthhfpddi-ioctl_bthhfp_device_get_descriptor) request to the Hands-free profile (HFP) audio driver. The requested information is returned in the form of a [**BTHHFP_DESCRIPTOR**](/windows-hardware/drivers/ddi/bthhfpddi/ns-bthhfpddi-_bthhfp_descriptor) structure, plus an other data referenced by the structure. The audio driver then calls IoSetDeviceInterfacePropertyData to set DEVPKEY_DeviceInterface_FriendlyName to the value in the *FriendlyName* field of the **BTHHFP_DESCRIPTOR** structure. The audio driver sets the parameters to IoSetDeviceInterfacePropertyData as follows: -- SymbolicLinkName = the string returned from IoRegisterDeviceInterface - -- PropertyKey = DEVPKEY\_DeviceInterface\_FriendlyName +- SymbolicLinkName = the string returned from IoRegisterDeviceInterface +- PropertyKey = DEVPKEY_DeviceInterface_FriendlyName +- Lcid = LOCALE_NEUTRAL +- Flags = PLUGPLAY_PROPERTY_PERSISTENT +- Type = DEVPROP_TYPE_STRING_INDIRECT +- Size = BTHHFP_DESCRIPTOR.FriendlyName.Length + sizeof(UNICODE_NULL) +- Data = BTHHFP_DESCRIPTOR.FriendlyName.Buffer -- Lcid = LOCALE\_NEUTRAL +## USB Bluetooth controller sideband SCO transport -- Flags = PLUGPLAY\_PROPERTY\_PERSISTENT +To have the USB Bluetooth controller identify itself as having sideband SCO transport, specify BthUsb_SidebandSco.NT, instead of BthUsb.NT that is normally used in the controller INF file. -- Type = DEVPROP\_TYPE\_STRING\_INDIRECT - -- Size = BTHHFP\_DESCRIPTOR.FriendlyName.Length + sizeof(UNICODE\_NULL) +```inf +Needs=BthUsb_SidebandSco.NT +``` -- Data = BTHHFP\_DESCRIPTOR.FriendlyName.Buffer +Setting this value means that a dedicated audio interface will be used to transfer audio in and out of the controller rather than USB endpoints. -## APO registration +For more information about the INF *Needs* directive, see [INF DDInstall section](/windows-hardware/drivers/install/inf-ddinstall-section). +## APO registration As described in [Setting Properties and Registry Values](setting-properties-and-registry-values.md), the driver can set registry values for a device interface. To register an APO, the audio driver sets several values on the device interface. These values are the same as those that are often set for APO registration in an INF, and the specific values will change from one audio driver to the next. @@ -46,9 +49,11 @@ HKR,"EPFX\\0",%PKEY_FX_Association%,,%KSNODETYPE_ANY% HKR,"EPFX\\0",%PKEY_FX_EndpointEffectClsid%,,%FX_DISCOVER_EFFECTS_APO_CLSID% ``` -**Note**  The syntax shown in the preceding snippet doesn't include instructions for registering the COM server of the APO. +> [!NOTE] +> The syntax shown in the preceding snippet doesn't include instructions for registering the COM server of the APO. + +## Related topics - +[Audio Processing Object Architecture](audio-processing-object-architecture.md) -## Related topics -[Related Design Guidelines](related-design-guidelines.md) +[Implementing Audio Processing Objects](implementing-audio-processing-objects.md) \ No newline at end of file diff --git a/windows-driver-docs-pr/audio/setting-properties-and-registry-values.md b/windows-driver-docs-pr/audio/setting-properties-and-registry-values.md index fee0ad36f2..e3dadf6897 100644 --- a/windows-driver-docs-pr/audio/setting-properties-and-registry-values.md +++ b/windows-driver-docs-pr/audio/setting-properties-and-registry-values.md @@ -1,66 +1,51 @@ --- -title: Setting Properties and Registry Values -description: The Setting Properties and Registry Values topic describes how a Port Class audio driver can set properties and registry values for a PnP device interface. +title: Setting properties and registry values +description: Learn how a Port Class audio driver can set properties and registry values for a PnP device interface. ms.date: 04/20/2017 --- -# Setting Properties and Registry Values +# Setting properties and registry values +This guide explains how a Port Class audio driver can set properties and registry values for a PnP device interface. To properly register the device interface and set required values, the Portcls driver must follow these steps: -The Setting Properties and Registry Values topic describes how a Port Class audio driver can set properties and registry values for a PnP device interface. +## 1. Register the device interface -The port class audio driver, Portcls must perform the following steps to properly register the device interface and set required values. +Before calling `PcRegisterSubdevice` for the sub-device, the driver should call `IoRegisterDeviceInterface` to register the `KSCATEGORY_AUDIO` interface. This allows the driver to set interface properties and registry values before `PcRegisterSubdevice` registers and enables the interfaces. -## 1. Register the device interface +When calling `IoRegisterDeviceInterface`, the audio driver sets the parameters as follows: +- The `PhysicalDeviceObject` parameter is the `PDEVICE_OBJECT` retrieved from the `PcGetPhysicalDeviceObject` function. +- The `InterfaceClassGuid` is set to the interface's class GUID. +- The `ReferenceString` is the same as the `Name` parameter passed to `PcRegisterSubdevice`. -Before calling PcRegisterSubdevice for the sub-device, the driver can directly call IoRegisterDeviceInterface to register the KSCATEGORY\_AUDIO interface. This gives the driver a chance to set interface properties and registry values on the device interfaces before PcRegisterSubdevice registers and enables the interfaces. +After completing these tasks successfully, `IoRegisterDeviceInterface` returns a `SymbolicLinkName` for the registered interface. -The audio driver sets the parameters for IoRegisterDeviceInterface as follows. +## 2. Set registry values -- The PhysicalDeviceObject parameter is the PDEVICE\_OBJECT that the audio driver can retrieve from the PcGetPhysicalDeviceObject function. +The audio driver calls `IoOpenDeviceInterfaceRegistryKey` to obtain a handle to the device interface registry key. The parameters for `IoOpenDeviceInterfaceRegistryKey` are set as follows: -- The InterfaceClassGuid is set to the interface’s class GUID. +- The `SymbolicLinkName` is the string returned from `IoRegisterDeviceInterface` in the previous step. +- The `DesiredAccess` is set to `KEY_WRITE` (or other values if needed by the driver). -- The ReferenceString is the same as the Name parameter that the audio driver passes to PcRegisterSubdevice. +After completing these steps, `DeviceInterfaceKey` returns the opened registry key handle. The audio driver: -After the preceding tasks are completed successfully, IoRegisterDeviceInterface returns a SymbolicLinkName for the registered interface. +- Calls `ZwSetValueKey` to set registry values. +- Closes the registry key handle by calling `ZwClose`. -## 2. Set registry values +**Note:** If the driver needs to set values in a registry subkey, it should call `ZwCreateKey` to create the subkey. When preparing to call `ZwCreateKey`, the driver: +- Calls `InitializeObjectAttributes` and sets the `ObjectName` to the subkey path. +- Sets `Attributes` to `OBJ_CASE_INSENSITIVE | OBJ_KERNEL_HANDLE`. +- Sets `RootDirectory` to the handle returned by `IoOpenDeviceInterfaceRegistryKey`. +- Calls `ZwClose` to close any handle created by calling `ZwCreateKey`. -The audio driver calls IoOpenDeviceInterfaceRegistryKey to obtain a handle to the device interface registry key. The audio driver sets the parameters to IoOpenDeviceInterfaceRegistryKey as follows. +## 3. Set properties -The SymbolicLinkName is the string returned from IoRegisterDeviceInterface in the previous step. +The audio driver calls `IoSetDeviceInterfacePropertyData` to set properties. The parameters for `IoSetDeviceInterfacePropertyData` are set as follows: -The DesiredAccess is set to KEY\_WRITE (or other values if needed by the driver). - -After the preceding steps are completed successfully, DeviceInterfaceKey returns the opened registry key handle. The audio driver: - -- Calls ZwSetValueKey to set registry values - -- Closes the registry key handle by calling ZwClose - -**Note**  If the driver needs to set values in a registry subkey, then the driver calls ZwCreateKey to create the subkey. When preparing to call ZwCreateKey, the driver: -- Calls InitializeObjectAttributes, and sets the ObjectName to the subkey path - -- Sets Attributes to OBJ\_CASE\_INSENSITIVE | OBJ\_KERNEL\_HANDLE - -- Sets RootDirectory to the handle returned by IoOpenDeviceInterfaceRegistryKey - -- Calls ZwClose to close any handle created by calling ZwCreateKey - - - -## 3. Set properties - - -The audio driver calls IoSetDeviceInterfacePropertyData to set properties. The audio driver sets the parameters to IoSetDeviceInterfacePropertyData as follows: -- The SymbolicLinkName is the string returned from IoRegisterDeviceInterface. +- The `SymbolicLinkName` is the string returned from `IoRegisterDeviceInterface`. - The remaining parameters depend on the specific property being set. -## Related topics -[Related Design Guidelines](related-design-guidelines.md) - - +## See also +[Sample Audio Drivers](sample-audio-drivers.md) diff --git a/windows-driver-docs-pr/audio/startup.md b/windows-driver-docs-pr/audio/startup.md index 4c9882665a..2475ff8cc2 100644 --- a/windows-driver-docs-pr/audio/startup.md +++ b/windows-driver-docs-pr/audio/startup.md @@ -1,79 +1,68 @@ --- -title: HFP Device Startup -description: The HFP Device startup topic discusses what happens when a Bluetooth hands-free profile (HFP) device arrives in the audio system. -ms.date: 04/20/2017 +title: HFP device startup +description: This article discusses the process when a Bluetooth hands-free profile (HFP) device arrives in the audio system. +ms.date: 07/27/2023 --- -# HFP Device Startup +# HFP device startup +This article explains the process when a Bluetooth hands-free profile (HFP) device arrives in the audio system. -The HFP Device startup topic discusses what happens when a Bluetooth hands-free profile (HFP) device arrives in the audio system. +For each paired HFP device that arrives in the audio system, the Windows HFP driver registers a device interface in the GUID_DEVINTERFACE_BLUETOOTH_HFP_SCO_HCIBYPASS class. The audio driver uses device interface notifications to stay informed of all instances of the GUID_DEVINTERFACE_BLUETOOTH_HFP_SCO_HCIBYPASS interfaces. The audio driver calls IoRegisterPlugPlayNotification from within its AVStrMiniDevicePostStart driver routine (or from an equivalent Portcls routine) to register a callback to discover the currently installed HFP devices and to be notified of new HFP devices. -For each paired HFP device that arrives in the audio system, the Windows HFP driver registers a device interface in the GUID\_DEVINTERFACE\_BLUETOOTH\_HFP\_SCO\_HCIBYPASS class. The audio driver uses device interface notifications to stay informed of all instances of the GUID\_DEVINTERFACE\_BLUETOOTH\_HFP\_SCO\_HCIBYPASS interfaces. The audio driver calls IoRegisterPlugPlayNotification from within its AVStrMiniDevicePostStart driver routine (or from an equivalent Portcls routine) to register a callback to discover the currently installed HFP devices, and to be notified of new HFP devices. +When the audio driver calls IoRegisterPlugPlayNotification, the call is made using the following parameters: -When the audio driver calls IoRegisterPlugPlayNotification, the call is made using the following parameters. +- EventCategory is set to EventCategoryDeviceInterfaceChange. +- EventCategoryFlags is typically set to PNPNOTIFY_DEVICE_INTERFACE_INCLUDE_EXISTING_INTERFACES to receive immediate notifications of existing interfaces. However, some alternate audio driver designs might find existing interfaces through other means. +- EventCategoryData is set to GUID_DEVINTERFACE_BLUETOOTH_HFP_SCO_HCIBYPASS. +- DriverObject is set to the audio driver’s DriverObject. +- CallbackRoutine is set to a routine in the audio driver that will receive the notifications. -- EventCategory is set to EventCategoryDeviceInterfaceChange. +The following sections outline the tasks that the audio driver can perform for each registered instance of a paired HFP device. -- EventCategoryFlags is typically set to PNPNOTIFY\_DEVICE\_INTERFACE\_INCLUDE\_EXISTING\_INTERFACES in order to receive immediate notifications of existing interfaces. However some alternate audio driver designs might find existing interfaces through other means. +## Handling interface instances -- EventCategoryData is set to GUID\_DEVINTERFACE\_BLUETOOTH\_HFP\_SCO\_HCIBYPASS. +For each interface instance registered in the GUID_DEVINTERFACE_BLUETOOTH_HFP_SCO_HCIBYPASS class, the audio driver must use the following protocol for communication: -- DriverObject is set to the audio driver’s DriverObject. +- When Windows calls the audio driver’s callback routine registered when the audio driver called IoRegisterPlugPlayNotification, Windows passes a symbolic link for the HFP interface, using DEVICE_INTERFACE_CHANGE_NOTIFICATION.*SymbolicLinkName*. +- When the audio driver calls IoGetDeviceObjectPointer, the driver uses the symbolic link to get the HFP FileObject and the DeviceObject for the HFP device. +- When the audio driver sends IOCTLs to the HFP driver, the driver uses the HFP FileObject and the DeviceObject for the HFP device. -- CallbackRoutine is set to a routine in the audio driver that will receive the notifications. +## Retrieving static information -The following sections outline the tasks that the audio driver can performs for each registered instance of a paired HFP device. +The audio driver can retrieve static information from the HFP driver. For example, the HFP driver can provide the ksnodetype, the container id, and the friendly name of the paired HFP device. The audio driver can use this information to create and initialize a KS filter or filters representing the paired HFP device. The audio driver uses [**IOCTL_BTHHFP_DEVICE_GET_DESCRIPTOR**](/windows-hardware/drivers/ddi/bthhfpddi/ni-bthhfpddi-ioctl_bthhfp_device_get_descriptor) to get this information. -## Handling interface instances - - -For each interface instance that is registered in the GUID\_DEVINTERFACE\_BLUETOOTH\_HFP\_SCO\_HCIBYPASS class, the audio driver must use the following protocol for communication: - -When Windows calls the audio driver’s callback routine that was registered when the audio driver called IoRegisterPlugPlayNotification, Windows passes a symbolic link for the HFP interface, using DEVICE\_INTERFACE\_CHANGE\_NOTIFICATION.*SymbolicLinkName*. - -When the audio driver calls IoGetDeviceObjectPointer, the driver uses the symbolic link to get the HFP FileObject and the DeviceObject for the HFP device. - -When the audio driver sends IOCTLs to the HFP driver, the driver uses the HFP FileObject and the DeviceObject for the HFP device. - -## Retrieving static information - - -The audio driver can retrieve static information from the HFP driver. For example, the HFP driver can provide the ksnodetype, the container id and the friendly name of the paired HFP device. The audio driver can use this information to create and initialize a KS filter or filters representing the paired HFP device. The audio driver uses [**IOCTL\_BTHHFP\_DEVICE\_GET\_DESCRIPTOR**](/windows-hardware/drivers/ddi/bthhfpddi/ni-bthhfpddi-ioctl_bthhfp_device_get_descriptor) to get this information. - -The audio driver can also retrieve the Bluetooth address of the paired HFP device. Each paired HFP device has a unique Bluetooth address, and this can be useful as a unique identifier string. For more information, see [Obtaining Bluetooth Address of HF Device](obtaining-bluetooth-address-of-hf-device.md). - -## Creating, initializing audio-specific filter factory context +The audio driver can also retrieve the Bluetooth address of the paired HFP device. Each paired HFP device has a unique Bluetooth address, which can be useful as a unique identifier string. For more information, see [Obtaining Bluetooth Address of HF Device](obtaining-bluetooth-address-of-hf-device.md). +## Creating, initializing audio-specific filter factory context To create and initialize an audio-specific filter factory context, the audio driver must store the HFP DeviceObject and the HFP FileObject in the filter factory context, and then initialize the IsConnected field to false. -## Creating the KS filter factory - +## Creating the KS filter factory -For each device instance in the GUID\_DEVINTERFACE\_BLUETOOTH\_HFP\_SCO\_HCIBYPASS interface class, the audio driver creates and enables one or more filter factories. +For each device instance in the GUID_DEVINTERFACE_BLUETOOTH_HFP_SCO_HCIBYPASS interface class, the audio driver creates and enables one or more filter factories. If the audio driver is an AVStream driver, the audio driver calls KsCreateFilterFactory to add the new filter factory and KsFilterFactorySetDeviceClassesState to enable the factory. If the audio driver is a PortCls driver, then it indirectly creates and enables KS filter factories by calling PcRegisterSubdevice. For many PortCls audio driver designs, there are two sub-devices registered for a given paired HFP device. -Each filter factory (or, for PortCls audio drivers, each pair of filter factories) represents the audio functionality of a single paired HFP device. The audio driver creates separate filter factories for each paired HFP device represented by unique instances of GUID\_DEVINTERFACE\_BLUETOOTH\_HFP\_SCO\_HCIBYPASS interfaces. For each paired HFP device, the audio driver must use unique strings for the *RefString* parameter of KsCreateFilterFactory, or the *Name* parameter of PcRegisterSubdevice. The driver developer might find it useful to use the paired HFP device’s Bluetooth address string as a unique string. See [Obtaining Bluetooth Address of HF Device](obtaining-bluetooth-address-of-hf-device.md) for information about how to retrieve the unique string. +Each filter factory (or, for PortCls audio drivers, each pair of filter factories) represents the audio functionality of a single paired HFP device. The audio driver creates separate filter factories for each paired HFP device represented by unique instances of GUID_DEVINTERFACE_BLUETOOTH_HFP_SCO_HCIBYPASS interfaces. For each paired HFP device, the audio driver must use unique strings for the *RefString* parameter of KsCreateFilterFactory, or the *Name* parameter of PcRegisterSubdevice. The driver developer might find it useful to use the paired HFP device’s Bluetooth address string as a unique string. See [Obtaining Bluetooth Address of HF Device](obtaining-bluetooth-address-of-hf-device.md) for information about how to retrieve the unique string. -Note that there is no specific maximum number of possible paired HFP devices, so the audio driver should avoid hard coding specific limitations. Instead, the audio driver must correctly handle dynamic arrival and removal of multiple GUID\_DEVINTERFACE\_BLUETOOTH\_HFP\_SCO\_HCIBYPASS interfaces. +Note that there is no specific maximum number of possible paired HFP devices, so the audio driver should avoid hard coding specific limitations. Instead, the audio driver must correctly handle dynamic arrival and removal of multiple GUID_DEVINTERFACE_BLUETOOTH_HFP_SCO_HCIBYPASS interfaces. -As a practical matter, however, a PortCls driver must specify a maximum number of sub-devices when it calls PcAddAdapterDevice. PcAddAdapterDevice pre-allocates extra memory for each potential sub-device. The audio driver developer should select a number high enough to accommodate many paired devices, but at the same time select a number that doesn't result in a waste of resources. For example, supporting only 2 HFP devices might be inadequate, and supporting 2000 would certainly result in overextended resources. However, supporting 16 is likely to be reasonable. +As a practical matter, however, a PortCls driver must specify a maximum number of sub-devices when it calls PcAddAdapterDevice. PcAddAdapterDevice pre-allocates extra memory for each potential sub-device. The audio driver developer should select a number high enough to accommodate many paired devices, but at the same time select a number that doesn't result in a waste of resources. For example, supporting only two HFP devices might be inadequate, and supporting two thousand would certainly result in overextended resources. However, supporting sixteen is likely to be reasonable. -If at runtime the audio driver is notified of another GUID\_DEVINTERFACE\_BLUETOOTH\_HFP\_SCO\_HCIBYPASS interface, but has already registered its maximum number of sub-devices, then the audio driver can invoke some algorithm to choose a paired HFP device whose sub-devices it can unregister to make room for the new HFP device. For example, the audio driver could keep track of the HFP device with the oldest connection. Whereas a simpler but perhaps less user-friendly audio driver could simply ignore additional GUID\_DEVINTERFACE\_BLUETOOTH\_HFP\_SCO\_HCIBYPASS interface after reaching its maximum. - -## Sending the get connection status IOCTL +If at runtime the audio driver is notified of another GUID_DEVINTERFACE_BLUETOOTH_HFP_SCO_HCIBYPASS interface, but has already registered its maximum number of sub-devices, then the audio driver can invoke some algorithm to choose a paired HFP device whose sub-devices it can unregister to make room for the new HFP device. For example, the audio driver could keep track of the HFP device with the oldest connection. Whereas a simpler but perhaps less user-friendly audio driver could simply ignore additional GUID_DEVINTERFACE_BLUETOOTH_HFP_SCO_HCIBYPASS interface after reaching its maximum. +## Sending the get connection status IOCTL The audio driver sends the get connection status IOCTL to get information about any changes that have occurred in the connection. -## Sending the get volume status IOCTL - +## Sending the get volume status IOCTL The audio driver sends the get volume status IOCTL to get information about any changes in volume level that have occurred in the volume status of the headset. -## Related topics -[**IOCTL\_BTHHFP\_DEVICE\_GET\_DESCRIPTOR**](/windows-hardware/drivers/ddi/bthhfpddi/ni-bthhfpddi-ioctl_bthhfp_device_get_descriptor) -[Theory of Operation](theory-of-operation.md) -[Obtaining Bluetooth Address of HF Device](obtaining-bluetooth-address-of-hf-device.md) +## Related topics + +- **[IOCTL_BTHHFP_DEVICE_GET_DESCRIPTOR](/windows-hardware/drivers/ddi/bthhfpddi/ni-bthhfpddi-ioctl_bthhfp_device_get_descriptor)** +- [Bluetooth HFP bypass audio streaming](bluetooth-hfp-bypass-audio-streaming.md) +- [Obtaining Bluetooth Address of HF Device](obtaining-bluetooth-address-of-hf-device.md) +- [Bluetooth Low Energy (LE) Audio](../bluetooth/bluetooth-low-energy-audio.md) diff --git a/windows-driver-docs-pr/audio/theory-of-operation.md b/windows-driver-docs-pr/audio/theory-of-operation.md deleted file mode 100644 index 1f41a13358..0000000000 --- a/windows-driver-docs-pr/audio/theory-of-operation.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Theory of Operation -description: This theory of operation topic explains the theory behind the inner working of the new Windows 8.1. -ms.date: 04/20/2017 ---- - -# Theory of Operation - - -This theory of operation topic explains the theory behind the inner working of the new Windows 8.1 support for Bluetooth bypass audio streaming. - -When Bluetooth audio is in bypass mode, the audio control path flows through some other hardware connection to the Bluetooth controller, rather than through the host controller interface (HCI). This other hardware connection is often I2S, but can be any interface determined by the Bluetooth host controller. This set of topics refers to this connection as a “bypass” or “sideband” connection. - -While audio I/O occurs through the bypass connection, the over-the-air synchronous connection oriented (SCO) audio stream is still managed through the HCI. Windows 8 provides a Bluetooth Hands-Free profile (HFP) driver to hide most of the complexities of managing the SCO connection and other aspects of the Hands-Free profile. However a custom audio driver controls audio data I/O between Windows and the bypass connection. - -The separation of roles between the HFP driver and the custom control driver for audio I/O data, means that efficient communication must be established between the Windows HFP driver and the custom audio driver. This communication is handled by a set of IOCTLs that are passed from the custom audio driver to the Windows HFP driver. - -Typically the bypass connection itself is always present. The PnP service always enumerates the hardware that includes this connection, and then loads the required audio driver. However, the audio system may or may not have any HFP headsets paired and the bypass connection is only useful if at least one HFP headset is paired. - -For each paired HFP device, the Windows HFP driver registers and enables a device interface in the GUID\_DEVINTERFACE\_BLUETOOTH\_HFP\_SCO\_HCIBYPASS interface class. So the following conditions are true for HFP devices: - -- When Windows activates the HFP driver (normally during boot up), the HFP driver registers and enables an interface for each paired HFP device. - -- When an HFP device is first paired, with Windows already up and running, the HFP driver registers and enables an interface for the device. - -- If there are n paired HFP devices, the Windows HFP driver registers n instances of the device interface. - -- When a paired HFP device is removed, the Windows HFP driver disables the device interface. - -- When Windows stops the HFP driver (normally during shutdown or reboot), the HFP driver disables the interface for each paired HFP device. - -- The audio driver must handle multiple arrivals and removals of interfaces at any time, not just during startup or shutdown. - -The following topics provide more information about the connection life cycle and some design features of an HFP device and its audio driver. - -[HFP Device Startup](startup.md) - -[HFP Device Connection](hfp-device-connection.md) - -[HFP Device Removal](removal.md) - -[Kernel Streaming Considerations](kernel-streaming-considerations.md) - -[Audio Endpoint Container ID](audio-endpoint-container-id.md) - -[Management of I2S and SCO Resources](management-of-i2s-and-sco-resources.md) - - - - - - - - diff --git a/windows-driver-docs-pr/audio/toc.yml b/windows-driver-docs-pr/audio/toc.yml index f84a5892be..4ec87c5e91 100644 --- a/windows-driver-docs-pr/audio/toc.yml +++ b/windows-driver-docs-pr/audio/toc.yml @@ -7,12 +7,30 @@ - name: "ACX - Audio Class Extensions" # Auto-expanded node items: - - name: "ACX - Audio Class Extensions Overview" + - name: "ACX audio class extensions overview" href: acx-audio-class-extensions-overview.md - - name: "ACX - Summary of ACX Objects" + - name: "ACX version information" + href: acx-version-overview.md + - name: "ACX summary of ACX objects" href: acx-summary-of-objects.md - - name: "ACX - Multi stack cross driver communications" - href: acx-audio-multi-stack.md + - name: "ACX reference documentation" + href: acx-reference.md + - name: "ACX streaming" + href: acx-streaming.md + - name: "ACX targets and synchronization" + href: acx-targets.md + - name: "ACX IO request packet IRPs" + href: acx-irps.md + - name: "ACX device enumeration" + href: acx-device-enumeration.md + - name: "ACX power management" + href: acx-power-management.md + - name: "ACX multi circuit composition" + href: acx-multi-circuit-composition.md + - name: "ACX multi stack cross driver communications" + href: acx-multi-stack.md + - name: "ACX logging and debugging" + href: acx-logging-and-debugging.md - name: "WDM Audio Drivers Overview" # Auto-expanded node items: @@ -360,43 +378,29 @@ href: windows-11-apis-for-audio-processing-objects.md - name: "Audio Hardware Resource Management" href: audio-hardware-resource-management.md - - name: "Bluetooth Bypass Guidelines for Audio Drivers" + - name: "Bluetooth HFP Bypass Guidelines for Audio Drivers" # Auto-expanded node items: - - name: "Bluetooth Bypass Guidelines for Audio Drivers" + - name: "Bluetooth HFP bypass guidelines for audio drivers" href: bluetooth-bypass-guidelines-for-audio-drivers.md - - name: "Windows Bluetooth host controller interface (HCI) Architectural Overview" - href: btth-architectural-overview.md - - name: "Theory of Operation" -# Auto-expanded node - items: - - name: "Theory of Operation" - href: theory-of-operation.md - - name: "HFP Device Startup" - href: startup.md - - name: "HFP Device Connection" - href: hfp-device-connection.md - - name: "HFP Device Removal" - href: removal.md - - name: "Kernel Streaming Considerations" - href: kernel-streaming-considerations.md - - name: "Audio Endpoint Container ID" - href: audio-endpoint-container-id.md - - name: "Management of I2S and SCO Resources" - href: management-of-i2s-and-sco-resources.md - - name: "Bluetooth Bypass DDI Reference" - href: bluetooth-bypass-ddi-reference.md - - name: "Related Design Guidelines" -# Auto-expanded node - items: - - name: "Related Design Guidelines" - href: related-design-guidelines.md - - name: "Setting Properties and Registry Values" - href: setting-properties-and-registry-values.md - - name: "Setting Friendly Names, Registering APOs" - href: setting-friendly-name--registering-apos.md - - name: "Obtaining Bluetooth Address of HF Device" - href: obtaining-bluetooth-address-of-hf-device.md + - name: "Bluetooth HFP bypass audio streaming" + href: bluetooth-hfp-bypass-audio-streaming.md + - name: "HFP device startup" + href: startup.md + - name: "HFP device connection" + href: hfp-device-connection.md + - name: "HFP device removal" + href: removal.md + - name: "Kernel streaming considerations" + href: kernel-streaming-considerations.md + - name: "Audio endpoint container ID" + href: audio-endpoint-container-id.md + - name: "Setting properties and registry values" + href: setting-properties-and-registry-values.md + - name: "Setting friendly names, sideband SCO transport and registering APOs" + href: setting-friendly-name--registering-apos.md + - name: "Obtaining bluetooth address of HF device" + href: obtaining-bluetooth-address-of-hf-device.md - name: "Hardware-Offloaded Audio Processing" # Auto-expanded node items: @@ -492,6 +496,8 @@ href: format-negotiation.md - name: "Dynamic Format Change" href: dynamic-format-change.md + - name: "Audio Processing Objects Utility Functions" + href: audio-processing-objects-utility-functions.md - name: "Combine Custom and Windows APOs" href: combine-custom-and-windows-apos.md - name: "Windows Audio Processing Objects" @@ -897,10 +903,22 @@ href: obtaining-a-device-interface-name.md - name: "Music Technology GUIDs" href: music-technology-guids.md + - name: "DRV_QUERYDEVICEINTERFACE function" + href: drv-querydeviceinterface.md + - name: "DRV_QUERYDEVICEINTERFACESIZE function" + href: drv-querydeviceinterfacesize.md + - name: "DRV_QUERYDEVNODE function" + href: drv-querydevnode.md + - name: "DRV_QUERYMAPPABLE function" + href: drv-querymappable.md + - name: "DRVM_MAPPER_CONSOLEVOICECOM_GET function" + href: drvm-mapper-consolevoicecom-get.md + - name: "DRVM_MAPPER_PREFERRED_GET function" + href: drvm-mapper-preferred-get.md - name: "Audio Devices Troubleshooting" # Auto-expanded node items: - - name: "Audio Devices Troubleshooting Overview" + - name: "Audio devices troubleshooting overview" href: audio-devices-troubleshooting.md - name: "USB Audio Device Not Playing" href: usb-audio-not-playing.md @@ -1121,7 +1139,54 @@ - name: "DRM Functions" href: drm-functions.md - name: "Audio Device Messages for MIDI" - href: audio-device-messages-for-midi.md +# Auto-expanded node + items: + - name: "Audio Device Messages for MIDI" + href: audio-device-messages-for-midi.md + - name: "modMessage function" + href: mod-message.md + - name: "MODM_CACHEDRUMPATCHES function" + href: modm-cachedrumpatches.md + - name: "MODM_CACHEPATCHES function" + href: modm-cachepatches.md + - name: "MODM_DATA function" + href: modm-data.md + - name: "MODM_GETDEVCAPS function" + href: modm-getdevcaps.md + - name: "MODM_GETNUMDEVS function" + href: modm-getnumdevs.md + - name: "MODM_GETPOS function" + href: modm-getpos.md + - name: "MODM_GETVOLUME function" + href: modm-getvolume.md + - name: "MODM_LONGDATA function" + href: modm-longdata.md + - name: "MODM_OPEN function" + href: modm-open.md + - name: "MODM_PAUSE function" + href: modm-pause.md + - name: "MODM_PREPARE function" + href: modm-prepare.md + - name: "MODM_PROPERTIES function" + href: modm-properties.md + - name: "MODM_RESET function" + href: modm-reset.md + - name: "MODM_RESTART function" + href: modm-restart.md + - name: "MODM_SETVOLUME function" + href: modm-setvolume.md + - name: "MODM_STOP function" + href: modm-stop.md + - name: "MODM_STRMDATA function" + href: modm-strmdata.md + - name: "MODM_UNPREPARE function" + href: modm-unprepare.md + - name: "MOM_CLOSE function" + href: mom-close.md + - name: "MOM_DONE function" + href: mom-done.md + - name: "MOM_OPEN function" + href: mom-open.md - name: "Legacy Audio Device Messages" href: legacy-audio-device-messages.md - name: "Audio INF File Settings" @@ -1249,6 +1314,8 @@ href: ksjack-description.md - name: "KSJACK_DESCRIPTION2" href: ksjack-description2.md + - name: "KSJACK_DESCRIPTION3" + href: ksjack-description3.md - name: "KSPROPERTY_AC3_ALTERNATE_AUDIO" href: ksproperty-ac3-alternate-audio.md - name: "KSPROPERTY_AC3_BIT_STREAM_MODE" @@ -1470,7 +1537,9 @@ - name: "KSPROPERTY_JACK_DESCRIPTION" href: ksproperty-jack-description.md - name: "KSPROPERTY_JACK_DESCRIPTION2" - href: ksproperty-jack-description2.md + href: ksproperty-jack-description2.md + - name: "KSPROPERTY_JACK_DESCRIPTION3" + href: ksproperty-jack-description3.md - name: "KSPROPERTY_JACK_SINK_INFO" href: ksproperty-jack-sink-info.md - name: "KSPROPERTY_ONESHOT_DISCONNECT" diff --git a/windows-driver-docs-pr/audio/topology-pins.md b/windows-driver-docs-pr/audio/topology-pins.md index 8186b3a161..86cadffb96 100644 --- a/windows-driver-docs-pr/audio/topology-pins.md +++ b/windows-driver-docs-pr/audio/topology-pins.md @@ -14,7 +14,7 @@ keywords: - translating pins WDK audio - pin factories WDK audio - PCPIN_DESCRIPTOR structure -ms.date: 04/20/2017 +ms.date: 11/14/2022 --- # Topology Pins @@ -51,88 +51,32 @@ WDMAud converts the information from the miniport driver's pin descriptor into a Indicates the type of data stream that the mixer line transports. For example, the target type for a wave output (rendering) stream is MIXERLINE\_TARGETTYPE\_WAVEOUT, and the target type for a wave input (capture) stream is MIXERLINE\_TARGETTYPE\_WAVEIN. -For more information about the MIXERLINE structure, see the Microsoft Windows SDK documentation. +For more information, see the [MIXERLINE structure](/windows/win32/api/mmeapi/ns-mmeapi-mixerline) in the SDK documentation. -The following two tables show how WDMAud translates input (KSPIN\_DATAFLOW\_IN) pins to source mixer lines. The first table shows how the input pin **KS pin category GUID**s map to the associated MIXERLINE target types. +The following two tables show how WDMAud translates input (KSPIN\_DATAFLOW\_IN) pins source mixer lines. -PCPIN\_DESCRIPTOR values -MIXERLINE values -KS pin category GUID -Bridge pin? -Target type -KSNODETYPE\_MICROPHONE +The first table shows how the input pin KS pin category GUIDs (PCPIN\_DESCRIPTOR values) map to the associated MIXERLINE target types. -KSNODETYPE\_DESKTOP\_MICROPHONE --- +KS pin category GUID | Bridge pin? | MIXERLINE Target type +|--------------------|-------------|----------------------| +KSNODETYPE\_MICROPHONE | - | MIXERLINE\_TARGETTYPE\_WAVEIN +KSNODETYPE\_DESKTOP\_MICROPHONE | - | MIXERLINE\_TARGETTYPE\_WAVEIN| +KSNODETYPE\_LEGACY\_AUDIO\_CONNECTOR | - | MIXERLINE\_TARGETTYPE\_WAVEOUT +KSCATEGORY\_AUDIO | - |MIXERLINE\_TARGETTYPE\_WAVEOUT | +KSNODETYPE\_SPEAKER | - | MIXERLINE\_TARGETTYPE\_WAVEOUT| +KSNODETYPE\_CD\_PLAYER | - | MIXERLINE\_TARGETTYPE\_UNDEFINED +KSNODETYPE\_SYNTHESIZER | - | MIXERLINE\_TARGETTYPE\_MIDIOUT +KSNODETYPE\_LINE\_CONNECTOR | - | MIXERLINE\_TARGETTYPE\_UNDEFINED +KSNODETYPE\_TELEPHONE | - | MIXERLINE\_TARGETTYPE\_UNDEFINED +KSNODETYPE\_PHONE\_LINE| - | MIXERLINE\_TARGETTYPE\_UNDEFINED +KSNODETYPE\_DOWN\_LINE\_PHONE | - | MIXERLINE\_TARGETTYPE\_UNDEFINED +KSNODETYPE\_ANALOG\_CONNECTOR | Yes | MIXERLINE\_TARGETTYPE\_WAVEIN +KSNODETYPE\_ANALOG\_CONNECTOR | No |MIXERLINE\_TARGETTYPE\_WAVEOUT +KSNODETYPE\_SPDIF\_INTERFACE | Yes | MIXERLINE\_TARGETTYPE\_WAVEIN +KSNODETYPE\_SPDIF\_INTERFACE | No | MIXERLINE\_TARGETTYPE\_WAVEOUT -MIXERLINE\_TARGETTYPE\_WAVEIN - -KSNODETYPE\_LEGACY\_AUDIO\_CONNECTOR - -KSCATEGORY\_AUDIO - -KSNODETYPE\_SPEAKER - --- - -MIXERLINE\_TARGETTYPE\_WAVEOUT - -KSNODETYPE\_CD\_PLAYER - --- - -MIXERLINE\_TARGETTYPE\_UNDEFINED - -KSNODETYPE\_SYNTHESIZER - --- - -MIXERLINE\_TARGETTYPE\_MIDIOUT - -KSNODETYPE\_LINE\_CONNECTOR - --- - -MIXERLINE\_TARGETTYPE\_UNDEFINED - -KSNODETYPE\_TELEPHONE - -KSNODETYPE\_PHONE\_LINE - -KSNODETYPE\_DOWN\_LINE\_PHONE - --- - -MIXERLINE\_TARGETTYPE\_UNDEFINED - -KSNODETYPE\_ANALOG\_CONNECTOR - -Yes - -MIXERLINE\_TARGETTYPE\_WAVEIN - -KSNODETYPE\_ANALOG\_CONNECTOR - -No - -MIXERLINE\_TARGETTYPE\_WAVEOUT - -KSNODETYPE\_SPDIF\_INTERFACE - -Yes - -MIXERLINE\_TARGETTYPE\_WAVEIN - -KSNODETYPE\_SPDIF\_INTERFACE - -No - -MIXERLINE\_TARGETTYPE\_WAVEOUT - - - -The following table shows how the input pin **KS pin category GUID**s map to the associated MIXERLINE component types. +The following table shows how the input pin KS pin category GUIDs map to the associated MIXERLINE component types.
@@ -198,86 +142,34 @@ The following table shows how the input pin **KS pin category GUID**s map to the
- - In the preceding tables, the left column specifies the pin category GUID from the pin's PCPIN\_DESCRIPTOR structure, and the right columns specify the corresponding target type and component type for the MIXERLINE structure. The entries in the column labeled "Bridge Pin?" indicate whether the pin is a bridge pin. A "Yes" means that the pin communications type is KSPIN\_COMMUNICATION\_BRIDGE. A "No" means that the pin communications type is a KSPIN\_COMMUNICATION\_*Xxx* value other than KSPIN\_COMMUNICATION\_BRIDGE. If WDMAud ignores the pin communications type when translating the pin parameters to mixer-line parameters, the "Bridge Pin?" entry is a dash (-). For all pin categories that do not appear in the preceding tables, WDMAud translates the input pins to source mixer lines with target types of MIXERLINE\_TARGETTYPE\_UNDEFINED and component types of MIXERLINE\_COMPONENTTYPE\_SRC\_UNDEFINED. -The following tables show how WDMAud translates output (KSPIN\_DATAFLOW\_OUT) pins to destination mixer lines. The column headings have the same meanings as in the preceding table. The first table shows how the output pin **KS pin category GUID**s map to the associated MIXERLINE target types. - -PCPIN\_DESCRIPTOR values -MIXERLINE values -KS pin category GUID -Bridge pin? -Target type -KSNODETYPE\_SPEAKER - -KSNODETYPE\_DESKTOP\_SPEAKER - -KSNODETYPE\_ROOM\_SPEAKER - -KSNODETYPE\_COMMUNICATION\_SPEAKER - --- - -MIXERLINE\_TARGETTYPE\_WAVEOUT - -KSCATEGORY\_AUDIO - -PINNAME\_CAPTURE - --- - -MIXERLINE\_TARGETTYPE\_WAVEIN - -KSNODETYPE\_HEADPHONES - -KSNODETYPE\_HEAD\_MOUNTED\_DISPLAY\_AUDIO - --- - -MIXERLINE\_TARGETTYPE\_WAVEOUT - -KSNODETYPE\_TELEPHONE - -KSNODETYPE\_PHONE\_LINE - -KSNODETYPE\_DOWN\_LINE\_PHONE - --- - -MIXERLINE\_TARGETTYPE\_UNDEFINED - -KSNODETYPE\_ANALOG\_CONNECTOR - -Yes - -MIXERLINE\_TARGETTYPE\_WAVEOUT - -KSNODETYPE\_ANALOG\_CONNECTOR - -No - -MIXERLINE\_TARGETTYPE\_WAVEIN - -KSNODETYPE\_SPDIF\_INTERFACE - -Yes - -MIXERLINE\_TARGETTYPE\_WAVEOUT - -KSNODETYPE\_SPDIF\_INTERFACE - -No - -MIXERLINE\_TARGETTYPE\_WAVEIN - - - -The following table shows how the output pin **KS pin category GUID**s map to the associated MIXERLINE component types. +The following tables show how WDMAud translates output (KSPIN\_DATAFLOW\_OUT) pins to destination mixer lines. The column headings have the same meanings as in the preceding table. The first table shows how the output pin KS pin category GUIDs map to the associated MIXERLINE target types. + + +KS pin category GUID | Bridge pin? | MIXERLINE Target type +|--------------------|-------------|----------------------| +KSNODETYPE\_SPEAKER | - | MIXERLINE\_TARGETTYPE\_WAVEOUT +KSNODETYPE\_DESKTOP\_SPEAKER | - | MIXERLINE\_TARGETTYPE\_WAVEOUT +KSNODETYPE\_ROOM\_SPEAKER | - | MIXERLINE\_TARGETTYPE\_WAVEOUT +KSNODETYPE\_COMMUNICATION\_SPEAKER | - | MIXERLINE\_TARGETTYPE\_WAVEOUT +KSCATEGORY\_AUDIO | - | MIXERLINE\_TARGETTYPE\_WAVEIN +PINNAME\_CAPTURE | - | MIXERLINE\_TARGETTYPE\_WAVEIN +KSNODETYPE\_HEADPHONES | - | MIXERLINE\_TARGETTYPE\_WAVEOUT +KSNODETYPE\_HEAD\_MOUNTED\_DISPLAY\_AUDIO | - | MIXERLINE\_TARGETTYPE\_WAVEOUT +KSNODETYPE\_TELEPHONE | - | MIXERLINE\_TARGETTYPE\_UNDEFINED +KSNODETYPE\_PHONE\_LINE | - | MIXERLINE\_TARGETTYPE\_UNDEFINED +KSNODETYPE\_DOWN\_LINE\_PHONE | - | MIXERLINE\_TARGETTYPE\_UNDEFINED +KSNODETYPE\_ANALOG\_CONNECTOR | Yes |MIXERLINE\_TARGETTYPE\_WAVEOUT +KSNODETYPE\_ANALOG\_CONNECTOR | No | MIXERLINE\_TARGETTYPE\_WAVEIN +KSNODETYPE\_SPDIF\_INTERFACE | Yes |MIXERLINE\_TARGETTYPE\_WAVEOUT +KSNODETYPE\_SPDIF\_INTERFACE | No | MIXERLINE\_TARGETTYPE\_WAVEIN + +The following table shows how the output pin KS pin category GUIDs map to the associated MIXERLINE component types. @@ -338,7 +230,6 @@ The following table shows how the output pin **KS pin category GUID**s map to th
- For all pin categories that do not appear in the preceding tables, WDMAud translates the output pins to destination mixer lines with target types of MIXERLINE\_TARGETTYPE\_UNDEFINED and component types of MIXERLINE\_COMPONENTTYPE\_DST\_UNDEFINED. In the preceding tables, most of the KS pin category GUIDs have KSNODETYPE\_*Xxx* names. These names are defined in header files Ksmedia.h and Dmusprop.h. (Two departures from this naming convention are GUIDs KSCATEGORY\_AUDIO and PINNAME\_CAPTURE, which are also defined in Ksmedia.h.) As described in [Topology Nodes](topology-nodes.md), KSNODETYPE\_*Xxx* GUIDs can also be used to designate KS node types. Most KSNODETYPE\_*Xxx* GUIDs specify either pin categories or node types, but not both. The exception is [**KSNODETYPE\_SYNTHESIZER**](./ksnodetype-synthesizer.md), which can specify either a pin category or a node type, depending on the context in which is used. For a list of KSNODETYPE\_*Xxx* GUIDs representing pin categories, see [Pin Category Property](pin-category-property.md). For a list of KSNODETYPE\_*Xxx* GUIDs representing node types, see [Audio Topology Nodes](./audio-topology-nodes.md). diff --git a/windows-driver-docs-pr/audio/usb-2-0-audio-drivers.md b/windows-driver-docs-pr/audio/usb-2-0-audio-drivers.md index 65aa133046..c14341fa3e 100644 --- a/windows-driver-docs-pr/audio/usb-2-0-audio-drivers.md +++ b/windows-driver-docs-pr/audio/usb-2-0-audio-drivers.md @@ -1,32 +1,32 @@ --- -title: USB Audio 2.0 Drivers -description: Starting with Windows 10, release 1703, a USB Audio 2.0 driver is shipped with Windows. This driver provides basic functionality. -ms.date: 12/19/2019 +title: USB Audio 2.0 drivers +description: A USB Audio 2.0 driver is shipped with Windows. This driver provides basic audio over USB functionality. +ms.date: 10/28/2022 ms.topic: article ms.custom: - CI 111498 - CSSTroubleshooting --- -# USB Audio 2.0 Drivers +# USB Audio 2.0 drivers -Starting with Windows 10, release 1703, a USB Audio 2.0 driver is shipped with Windows. It is designed to support the USB Audio 2.0 device class. The driver is a WaveRT audio port class miniport. For more information about the USB Audio 2.0 device class, see [https://www.usb.org/documents?search=&type%5B0%5D=55&items_per_page=50](https://www.usb.org/documents?search=&type%5B0%5D=55&items_per_page=50). +Starting with Windows 10, release 1703, a USB Audio 2.0 driver is shipped with Windows. It's designed to support the USB Audio 2.0 device class. The driver is a WaveRT audio port class miniport. -The driver is named: _usbaudio2.sys_ and the associated inf file is _usbaudio2.inf_. +The driver is named: *usbaudio2.sys* and the associated inf file is *usbaudio2.inf*. -The driver will identify in device manager as "USB Audio Class 2 Device". This name will be overwritten with a USB Product string, if it is available. +The driver will identify in device manager as "USB Audio Class 2 Device". This name will be overwritten with a USB product string, if it's available. The driver is automatically enabled when a compatible device is attached to the system. However, if a third-party driver exists on the system or Windows Update, that driver will be installed and override the class driver. ## Architecture -usbaudio2.sys fits within the wider architecture of Windows USB Audio as shown. +The *usbaudio2.sys* driver fits within the wider architecture of Windows USB Audio as shown. -![stack diagram showing Kmixer.sys at the top and a USB audio device at the bottom.](images/usb-2-0-audio-arch.png) +:::image type="content" source="images/usb-2-0-audio-arch.png" alt-text="A stack diagram showing ks.sys at the top and USB Audio devices at the bottom."::: ## Related USB specifications -The following USB specifications define USB Audio and are referenced in this topic. +The following USB specifications define USB Audio and are referenced in this article. - USB-2 refers to the Universal Serial Bus Specification, Revision 2.0 - ADC-2 refers to the USB Device Class Definition for Audio Devices, Release 2.0. @@ -36,7 +36,7 @@ The USB-IF is a special interest group that maintains the [Official USB Specific ## Audio formats -The driver supports the formats listed below. An alternate setting which specifies another format defined in FMT-2, or an unknown format, will be ignored. +The driver supports the formats listed below. An alternate setting, which specifies another format defined in FMT-2, or an unknown format, will be ignored. Type I formats (FMT-2 2.3.1): @@ -63,13 +63,13 @@ The driver supports all entity types defined in ADC-2 3.13. Each Terminal Entity must have a valid clock connection in compatible USB Audio 2.0 hardware. The clock path may optionally include Clock Multiplier and Clock Selector units and must end in a Clock Source Entity. -The driver supports one single clock source only. If a device implements multiple clock source entities and a clock selector, then the driver will use the clock source that is selected by default and will not modify the clock selector’s position. +The driver supports one single clock source only. If a device implements multiple clock source entities and a clock selector, then the driver will use the clock source that is selected by default and won't modify the clock selector's position. -A Processing Unit (ADC-2 3.13.9) with more than one input pin is not supported. +A Processing Unit (ADC-2 3.13.9) with more than one input pin isn't supported. -An Extension Unit (ADC-2 3.13.10) with more than one input pin is not supported. +An Extension Unit (ADC-2 3.13.10) with more than one input pin isn't supported. -Cyclic paths in the topology are not allowed. +Cyclic paths in the topology aren't allowed. ### Audio streaming @@ -79,17 +79,17 @@ The driver supports the following endpoint synchronization types (USB-2 5.12.4.1 - Synchronous IN and OUT - Adaptive IN and OUT -For the asynchronous OUT case the driver supports explicit feedback only. A feedback endpoint must be implemented in the respective alternate setting of the AS interface. The driver does not support implicit feedback. +For the asynchronous OUT case, the driver supports explicit feedback only. A feedback endpoint must be implemented in the respective alternate setting of the AS interface. The driver doesn't support implicit feedback. -There is currently limited support for devices using a shared clock for multiple endpoints. +There's currently limited support for devices using a shared clock for multiple endpoints. -For the Adaptive IN case the driver does not support a feedforward endpoint. If such an endpoint is present in the alternate setting, it will be ignored. The driver handles the Adaptive IN stream in the same way as an Asynchronous IN stream. +For the Adaptive IN case the driver doesn't support a feed forward endpoint. If such an endpoint is present in the alternate setting, it will be ignored. The driver handles the Adaptive IN stream in the same way as an Asynchronous IN stream. The size of isochronous packets created by the device must be within the limits specified in FMT-2.0 section 2.3.1.1. This means that the deviation of actual packet size from nominal size must not exceed +/- one audio slot (audio slot = channel count samples). ## Descriptors -An audio function must implement exactly one AudioControl Interface Descriptor (ADC-2 4.7) and one or more AudioStreaming Interface Descriptors (ADC-2 4.9). A function with an audio control interface but no streaming interface is not supported. +An audio function must implement exactly one AudioControl Interface Descriptor (ADC-2 4.7) and one or more AudioStreaming Interface Descriptors (ADC-2 4.9). A function with an audio control interface but no streaming interface isn't supported. The driver supports all descriptor types defined in ADC-2, section 4. The following subsections provide comments on some specific descriptor types. @@ -99,9 +99,9 @@ For details on this specification, refer to ADC-2 4.9.2. An AS interface descriptor must start with alternate setting zero with no endpoint (no bandwidth consumption) and further alternate settings must be specified in ascending order in compatible USB Audio 2.0 hardware. -An alternate setting with a format that is not supported by the driver will be ignored. +An alternate setting with a format that isn't supported by the driver will be ignored. -Each non-zero alternate setting must specify an isochronous data endpoint, and optionally a feedback endpoint. A non-zero alternate setting without any endpoint is not supported. +Each non-zero alternate setting must specify an isochronous data endpoint, and optionally a feedback endpoint. A non-zero alternate setting without any endpoint isn't supported. The bTerminalLink field must refer to a Terminal Entity in the topology and its value must be identical in all alternate settings of an AS interface. @@ -117,18 +117,18 @@ For details on this specification, refer to FMT-2 2.3.1.6. The following restrictions apply: -|Format |Subslot size |Bit resolution | -|----|----|----| -| Type I PCM format: | 1 <= bSubslotSize <= 4 | 8 <= bBitResolution <= 32 | -| Type I PCM8 format: | bSubslotSize == 1 | bBitResolution == 8 | -| Type I IEEE_FLOAT format: | bSubslotSize == 4 | bBitResolution == 32 | -| Type III IEC61937 formats: | bSubslotSize == 2 | bBitResolution == 16 | +| Format | Subslot size | Bit resolution | +|----------------------------|------------------------|---------------------------| +| Type I PCM format: | 1 <= bSubslotSize <= 4 | 8 <= bBitResolution <= 32 | +| Type I PCM8 format: | bSubslotSize == 1 | bBitResolution == 8 | +| Type I IEEE_FLOAT format: | bSubslotSize == 4 | bBitResolution == 32 | +| Type III IEC61937 formats: | bSubslotSize == 2 | bBitResolution == 16 | -### Class-Specific AS isochronous audio data endpoint descriptor +### Class-Specific AS isochronous audio data endpoint descriptor For details on this specification, refer to ADC-2 4.10.1.2. -The MaxPacketsOnly flag in the bmAttributes field is not supported and will be ignored. +The MaxPacketsOnly flag in the bmAttributes field isn't supported and will be ignored. The fields bmControls, bLockDelayUnits and wLockDelay will be ignored. @@ -162,13 +162,13 @@ At a minimum, a Clock Source Entity must implement Sampling Frequency Control GE The Sampling Frequency Control GET RANGE request returns a list of subranges (ADC-2 5.2.1). Each subrange describes a discrete frequency, or a frequency range. A discrete sampling frequency must be expressed by setting MIN and MAX fields to the respective frequency and RES to zero. Individual subranges must not overlap. If a subrange overlaps a previous one, it will be ignored by the driver. -A Clock Source Entity which implements one single fixed frequency only does not need to implement Sampling Frequency Control SET CUR. It implements GET CUR which returns the fixed frequency, and it implements GET RANGE which reports one single discrete frequency. +A Clock Source Entity that implements one single fixed frequency only doesn't need to implement Sampling Frequency Control SET CUR. It implements GET CUR, which returns the fixed frequency, and it implements GET RANGE, which reports one single discrete frequency. ### Clock selector entity For details on this specification, refer to ADC-2 5.2.5.2 -The USB Audio 2.0 driver does not support clock selection. The driver uses the Clock Source Entity which is selected by default and never issues a Clock Selector Control SET CUR request. The Clock Selector Control GET CUR request (ADC-2 5.2.5.2.1) must be implemented in compatible USB Audio 2.0 hardware. +The USB Audio 2.0 driver doesn't support clock selection. The driver uses the Clock Source Entity, which is selected by default and never issues a Clock Selector Control SET CUR request. The Clock Selector Control GET CUR request (ADC-2 5.2.5.2.1) must be implemented in compatible USB Audio 2.0 hardware. ### Feature unit @@ -178,15 +178,15 @@ The driver supports one single volume range only. If the Volume Control GET RANG The volume interval expressed by the MIN and MAX fields should be an integer multiple of the step size specified in the RES field. -If a feature unit implements single channel controls as well as a master control for Mute or Volume, then the driver uses the single channel controls and ignores the master control. +If a feature unit implements single channel controls and a master control for Mute or Volume, then the driver uses the single channel controls and ignores the master control. ## Additional Information for OEM and IHVs OEMs and IHVs should test their existing and new devices against the supplied in-box driver. -There is not any specific partner customization that is associated with the in-box USB Audio 2.0 driver. +There isn't any specific partner customization that is associated with the in-box USB Audio 2.0 driver. -This INF file entry (provided in a update to Windows Release 1703), is used to identify that the in-box driver is a generic device driver. +This INF file entry (provided in an update to Windows Release 1703), is used to identify that the in-box driver is a generic device driver. ```inf GenericDriverInstalled,,,,1 @@ -201,7 +201,7 @@ USB\Class_01&SubClass_02&Prot_20 USB\Class_01&SubClass_03&Prot_20 ``` -See the USB audio 2.0 specification for subclass types. +See the USB Audio 2.0 specification for subclass types. USB Audio 2.0 Devices with MIDI (subclass 0x03 above) will enumerate the MIDI function as a separate multi-function device with usbaudio.sys (USB Audio 1.0 driver) loaded. @@ -220,11 +220,11 @@ USB\Class_01&SubClass_02&Prot_20 USB\Class_01&SubClass_03&Prot_20 ``` -An arbitrary number of channels (greater than eight) are not supported in shared mode due to a limitation of the Windows audio stack. +An arbitrary number of channels (greater than eight) aren't supported in shared mode due to a limitation of the Windows audio stack. ## IHV USB Audio 2.0 drivers and updates -For IHV provided third party driver USB Audio 2.0 drivers, those drivers will continue to be preferred for their devices over our in-box driver unless they update their driver to explicitly override this behavior and use the in-box driver. +For IHV provided third party driver USB Audio 2.0 drivers, those drivers will continue to be preferred for their devices over our in-box driver unless they update their driver to explicitly override this behavior and use the in-box driver. ## Audio Jack Registry Descriptions @@ -237,7 +237,7 @@ The following describes the audio jack information settings in the registry: ```text REG_DWORD T_NrJacks # of the jack on this device REG_DWORD T_J_ChannelMapping Channel mask. The value is defined in ksmedia.h. e.g. SPEAKER_FRONT_RIGHT or KSAUDIO_SPEAKER_5POINT1_SURROUND -REG_DWORD T_J_ConnectorType The enum value is define in EPcxConnectionType. +REG_DWORD T_J_ConnectorType The enum value is define in EPcxConnectionType. REG_DWORD T_J_GeoLocation The enum value is define in EPcxGeoLocation. REG_DWORD T_J_GenLocation The enum value is define in EPcxGenLocation. REG_DWORD T_J_PortConnection The enum value is define in EPxcPortConnection. @@ -245,8 +245,8 @@ REG_DWORD T_J_Color The color needs to be represent by RGB ``` \ = terminal ID (As defined in the descriptor) - -\ = Jack number (1 ~ n). + +\ = Jack number (1 ~ n). Convention for \ and \ is: @@ -258,13 +258,13 @@ For example: T1_NrJacks, T1_J2_ChannelMapping, T1_J2_ConnectorType -For additional audio jack information, see [KSJACK_DESCRIPTION structure](./ksjack-description.md). +For more audio jack information, see [KSJACK_DESCRIPTION structure](./ksjack-description.md). These registry values can be set in various ways: -- By using custom INFs which wrap the in-box INF for the purpose to set these values. +- By using custom INFs, which wrap the in-box INF for the purpose to set these values. -- Directly by the h/w device via a Microsoft OS Descriptors for USB devices (see example below). For more information about creating these descriptors, see [Microsoft OS Descriptors for USB Devices](../usbcon/microsoft-defined-usb-descriptors.md). +- Directly by the hardware device via a Microsoft OS Descriptor for USB devices (see example below). For more information about creating these descriptors, see [Microsoft OS Descriptors for USB Devices](../usbcon/microsoft-defined-usb-descriptors.md). ### Microsoft OS Descriptors for USB Example @@ -289,7 +289,7 @@ UCHAR Example2_MSOS20DescriptorSetForUAC2 [0x76] = { 0x04, 0x00, // wDescriptorType – 5 for Registry Property 0x04, 0x00, // wPropertyDataType - 4 for REG_DWORD 0x34, 0x00, // wPropertyNameLength – 52 bytes - 0x54, 0x00, 0x30, 0x00, // Property Name - “T01_J01_ChannelMapping” + 0x54, 0x00, 0x30, 0x00, // Property Name - "T01_J01_ChannelMapping" 0x31, 0x00, 0x5f, 0x00, 0x4a, 0x00, 0x30, 0x00, 0x31, 0x00, 0x5f, 0x00, @@ -311,7 +311,7 @@ UCHAR Example2_MSOS20DescriptorSetForUAC2 [0x76] = { 0x04, 0x00, // wDescriptorType – 5 for Registry Property 0x04, 0x00, // wPropertyDataType - 4 for REG_DWORD 0x1C, 0x00, // wPropertyNameLength – 28 bytes - 0x54, 0x00, 0x30, 0x00, // Property Name - “T01_J01_Color” + 0x54, 0x00, 0x30, 0x00, // Property Name - "T01_J01_Color" 0x31, 0x00, 0x5f, 0x00, 0x4a, 0x00, 0x30, 0x00, 0x31, 0x00, 0x5f, 0x00, @@ -324,26 +324,23 @@ UCHAR Example2_MSOS20DescriptorSetForUAC2 [0x76] = { ## Troubleshooting -If the driver does not start, the system event log should be checked. The driver logs events which indicate the reason for the failure. Similarly, audio logs can be manually collected following the steps described in [this blog entry](https://matthewvaneerde.wordpress.com/2017/01/09/collecting-audio-logs-the-old-fashioned-way/). If the failure may indicate a driver problem, please report it using the Feedback Hub described below, and include the logs. +If the driver doesn't start, the system event log should be checked. The driver logs events that indicate the reason for the failure. Similarly, audio logs can be manually collected following the steps described in Matthew van Eerde's web log article, [Collecting audio logs the old-fashioned way](https://matthewvaneerde.wordpress.com/2017/01/09/collecting-audio-logs-the-old-fashioned-way/). If the failure may indicate a driver problem, please report it using the Feedback Hub described below, and include the logs. -For information on how to read logs for the USB Audio 2.0 class driver using supplemental TMF files, see [this blog entry](https://matthewvaneerde.wordpress.com/2016/09/26/report-problems-with-logs-and-suggest-features-with-the-feedback-hub//). For general information on working with TMF files, see [Displaying a Trace Log with a TMF File](../devtest/displaying-a-trace-log-with-a-tmf-file.md). +For information on how to read logs for the USB Audio 2.0 class driver using supplemental TMF files, see [Report problems, with logs, and suggest features, with the Feedback Hub](https://matthewvaneerde.wordpress.com/2016/09/26/report-problems-with-logs-and-suggest-features-with-the-feedback-hub/) on Matthew van Eerde's web log. For general information on working with TMF files, see [Displaying a Trace Log with a TMF File](../devtest/displaying-a-trace-log-with-a-tmf-file.md). -For information on "Audio services not responding" error and USB audio device does not work in Windows 10 version 1703 see, [USB Audio Not Playing](usb-audio-not-playing.md) +For information on "Audio services not responding" error and USB Audio device doesn't work in Windows 10 version 1703 see, [USB Audio Not Playing](usb-audio-not-playing.md) ## Feedback Hub -If you run into a problem with this driver, collect audio logs and then follow steps outlined in [this blog entry](/archive/blogs/matthew_van_eerde/report-problems-with-logs-and-suggest-features-with-the-feedback-hub) to bring it to our attention via the Feedback Hub. +If you run into a problem with this driver, collect audio logs and then follow steps outlined in [Report problems, with logs, and suggest features, with the Feedback Hub](https://matthewvaneerde.wordpress.com/2016/09/26/report-problems-with-logs-and-suggest-features-with-the-feedback-hub/) to bring it to our attention. ## Driver development -This USB Audio 2.0 class driver was developed by Thesycon and is supported by Microsoft. +This USB Audio 2.0 class driver was developed by [Thesycon](https://www.thesycon.info/eng/usb_audiodriver.shtml) and is supported by Microsoft. ### See also -[Windows Driver Model (WDM)](../kernel/writing-wdm-drivers.md) - -[Audio Drivers Overview](./getting-started-with-wdm-audio-drivers.md) - -[WaveRT Port Driver](./introducing-the-wavert-port-driver.md) - -[Low Latency Audio](./low-latency-audio.md) +- [Windows Driver Model (WDM)](../kernel/writing-wdm-drivers.md) +- [Audio Drivers Overview](./getting-started-with-wdm-audio-drivers.md) +- [WaveRT Port Driver](./introducing-the-wavert-port-driver.md) +- [Low Latency Audio](./low-latency-audio.md) diff --git a/windows-driver-docs-pr/audio/usb-audio-not-playing.md b/windows-driver-docs-pr/audio/usb-audio-not-playing.md index a564616f2c..98fb50248d 100644 --- a/windows-driver-docs-pr/audio/usb-audio-not-playing.md +++ b/windows-driver-docs-pr/audio/usb-audio-not-playing.md @@ -1,28 +1,31 @@ --- -title: USB Audio Not Playing -description: Audio Drivers Event Sets -ms.date: 12/19/2019 +title: USB audio device not playing +description: This article discusses the "Audio services not responding" error. +ms.date: 10/28/2022 --- -# USB Audio Not Playing (KB 4045958) "Audio services not responding" error and USB audio device does not work in Windows 10 version 1703 +# USB audio device not playing + +This article discusses the "Audio services not responding" error and USB audio device doesn't work in Windows 10 version 1703. ## Symptoms Consider the following scenario: -1. You connect a Universal Serial Bus (USB) audio device, such as an audio adapter or USB digital-to-analog converter (DAC), to a Windows 10 Version 1703-based computer for the first time. +1. You connect a Universal Serial Bus (USB) audio device, such as an audio adapter or USB digital-to-analog converter (DAC), to a Windows computer for the first time. 2. The operating system detects the device and loads the standard USB audio 2.0 driver (usbaudio2.sys). -3. Windows then downloads the device-specific driver from Windows Update. +3. Windows then downloads the device-specific driver from Windows Update. 4. The downloaded device driver replaces the usbaudio2.sys driver. -In this scenario, the device cannot be used, and the computer does not have sound. The speaker icon on the task bar is marked with an X mark. When you select the icon, you receive the following message: +In this scenario, the device can't be used, and the computer doesn't have sound. The speaker icon on the task bar is marked with an X mark. When you select the icon, you receive the following message: > Audio services not responding. Both the Windows Audio and the Windows Audio End Point Builder services must be running for audio to work correctly. ## Cause -This "audio not playing" problem occurs because the default USB audio 2.0 driver (usbaudio2.sys) uses the WaveRT port for operation but the device-specific driver does not. However, both drivers use the "wave" reference string when the device interface is registered. -When the device-specific driver replaces the default driver, the device interface that is created by usbaudio2.sys is still used because the reference strings overlap. Therefore, the operating system assumes that the new driver also supports the WaveRT port. Because the new driver does not support the WaveRT port, the system cannot access the driver. +This "audio not playing" problem occurs because the default USB audio 2.0 driver (usbaudio2.sys) uses the WaveRT port for operation but the device-specific driver doesn't. However, both drivers use the "wave" reference string when the device interface is registered. + +When the device-specific driver replaces the default driver, the device interface that is created by usbaudio2.sys is still used because the reference strings overlap. Therefore, the operating system assumes that the new driver also supports the WaveRT port. Because the new driver doesn't support the WaveRT port, the system can't access the driver. ## Resolution @@ -30,13 +33,15 @@ To fix this problem, use one of the following methods. ### Method 1 -Uninstall the device. To do this, follow these steps: +Follow these steps to uninstall the device: 1. Open Device Manager. -1. Select and hold (or double-click) the name of the device, and then select **Uninstall**. +1. Double-click the name of the device. +1. Select the **Driver** tab. +1. Select **Uninstall device**. -> Note: -> In step 2, don't select the **Delete the driver software for this device** check box. +> [!NOTE] +> Don't select the **Delete the driver software for this device** check box. ### Method 2 @@ -44,8 +49,8 @@ Connect the device to a different USB port. The problem may not occur if the dev ### Method 3 -If the device is not yet connected, install the device-specific driver first. You can do this by using the appropriate installer for the device. Then, connect the device. Windows now selects the device-specific driver instead of the default USB audio 2.0 driver. This method works in this situation because the problem occurs only if the device-specific driver replaces the default driver after the device is connected. +If the device isn't yet connected, install the device-specific driver first by using the installer for the device. Then, connect the device. Windows now selects the device-specific driver instead of the default USB audio 2.0 driver. This method works because the problem only occurs if the device-specific driver replaces the default driver after the device is connected. -## See Also +## See also -[Audio Devices Troubleshooting](audio-devices-troubleshooting.md) +- [Audio Devices Troubleshooting](audio-devices-troubleshooting.md) diff --git a/windows-driver-docs-pr/audio/usepositionlock.md b/windows-driver-docs-pr/audio/usepositionlock.md index 50a1b18feb..f3e0d20368 100644 --- a/windows-driver-docs-pr/audio/usepositionlock.md +++ b/windows-driver-docs-pr/audio/usepositionlock.md @@ -1,7 +1,7 @@ --- title: UsePositionLock description: The UsePositionLock registry value changes how PortCls serializes its I/O. -ms.date: 11/28/2017 +ms.date: 09/29/2022 --- # UsePositionLock @@ -12,18 +12,14 @@ The *UsePositionLock* registry value changes how PortCls serializes its I/O. Ena Use the following INF setting to enable this behavior. ```inf - [MyAudioDevice.AddReg] HKR, DispatchSettings, UsePositionLock, 3, 01, 00, 00, 00 ``` +When this value is set to 1 or above, portcls uses the streaming position lock to serialize the callbacks listed below. If it is not present or set to zero, the default behavior is to use the global device lock. This value is read the first time the device is added. -This INF setting creates the following registry value. The media GUID of {4d36e96c-e325-11ce-bfc1-08002be10318} and the <instance\#> of your audio device are used in the registry entry path. +This INF setting will be stored under the device instance in the registry whose path contains the media GUID of {4d36e96c-e325-11ce-bfc1-08002be10318}. -```text -\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Class\{4d36e96c-e325-11ce-bfc1-08002be10318}\\DispatchSettings\UsePositionLock -``` - -When this value is set to 1 or above, portcls uses the streaming position lock to serialize the callbacks listed below. If it is not present or set to zero, the default behavior is to use the global device lock. This value is read the first time the device is added. +This INF setting creates a registry value that contains the media GUID of {4d36e96c-e325-11ce-bfc1-08002be10318} that includes the instance of your audio device. The *UsePositionLock* setting is only supported on WaveRT and Topology filters. Portcls reads this registry value at device-add time and the setting persists until the functional device object (FDO) is removed. diff --git a/windows-driver-docs-pr/audio/voice-activation-mva.md b/windows-driver-docs-pr/audio/voice-activation-mva.md index 70319d87df..e116dc39e9 100644 --- a/windows-driver-docs-pr/audio/voice-activation-mva.md +++ b/windows-driver-docs-pr/audio/voice-activation-mva.md @@ -1,19 +1,19 @@ --- title: Multiple Voice Assistant description: The Multiple Voice Assistant platform provides support for additional voice assistants beyond Cortana. -ms.date: 09/08/2020 +ms.date: 04/13/2023 --- # Multiple Voice Assistant -The Multiple Voice Assistant platform provides support for additional voice assistants beyond Cortana. This allows other assistants be available on Windows devices such as PCs and wearables like HoloLens. Multiple voice assistants can be active on the same device using a set of supported keyword patterns. - -For information about implementing Windows Cortana, see [Voice Activation](voice-activation.md). +The Multiple Voice Assistant platform provides support for additional voice assistants in Windows. This allows other assistants be available on Windows devices such as PCs and wearables like HoloLens. Multiple voice assistants can be active on the same device using a set of supported keyword patterns. > [!NOTE] > Multiple Voice Assistant is supported starting with Windows 10 Version 1903. > +For information about implementing Windows Cortana, see [Voice Activation](voice-activation.md). + ## Voice Activation Voice activation is a feature that enables users to invoke a speech recognition engine from various device power states by saying a specific phrase. @@ -23,11 +23,12 @@ Implementing voice activation is a significant project and is a task completed b Voice activation allows users to quickly engage the voice assistant experience outside of their active context (i.e., what is currently on screen) by using their voice. Users often want to be able to instantly access an experience without having to physically interact with or touch a device. For an Xbox user this may be from not wanting to find and connect a controller. For PC users, they might want rapid access to an experience without having to perform multiple mouse, touch and/or keyboard actions, as in the case of a computer in the kitchen. Voice activation is powered by a keyword spotter (KWS) which reacts if the key phrase is detected. Key phrases may include key words such as "Hey Contoso." *Keyword detection* describes the detection of the keyword by either hardware or software. + Key phrases may be uttered by themselves ("Hey Contoso") as a staged command, or followed by a speech action composing a chained command ("Hey Contoso, where is my next meeting?") Microsoft provides an OS default keyword spotter (software keyword spotter) to provide voice assistant experience in cases where hardware keyword detection is unavailable. While this is currently available for Cortana, additional Microsoft configuration may be needed to onboard other voice assistants to do two-stage keyword detection. For more information contact `AskMVA@Microsoft.com`. -If KWS is to wake the device from a low powered state, the solution is known as Wake-on-Voice (WoV). For more information, see [Wake on Voice](#wake-on-voice). +If KWS is to wake the device from a low powered state, the solution is known as Wake-on-Voice (WoV). For more information, see [Wake on Voice](#wake-on-voice) later in this article. ## Glossary of Terms @@ -35,20 +36,20 @@ This glossary summarizes terms related to voice activation. |Term|Example/definition| |----|----| -| Staged Command | Example: Hey Contoso What's the weather? This is sometimes referred to as "two-shot command" or "keyword-only" | -| Chained Command | Example: Hey Contoso what's the weather? This is sometimes referred to as a "one-shot command" | -| Voice Activation | Example: "Hey Contoso" The scenario where keyword is detected in a predefined activation key phrase | -| Wake-on-Voice (WoV) | Technology that enables voice activation from a screen off, lower power state, to a screen on full power state | -|WoV from Modern Standby| Wake-on-Voice from a Modern Standby (S0ix) screen off state to a screen on full power (S0) state | -| Modern Standby | Windows Low Power Idle infrastructure - successor to Connected Standby (CS) in Windows 10. The first state of modern standby is when the screen is off. The deepest sleep state is when in DRIPS/Resiliency. For more information, see [Modern Standby](/windows-hardware/design/device-experiences/modern-standby)| -| KWS | Keyword spotter – the algorithm that provides the detection of "Hey Contoso" | +| Staged Command | Example: Hey Contoso What's the weather? This is sometimes referred to as "two-shot command" or "keyword-only". | +| Chained Command | Example: Hey Contoso what's the weather? This is sometimes referred to as a "one-shot command". | +| Voice Activation | Example: "Hey Contoso" The scenario where keyword is detected in a predefined activation key phrase. | +| Wake-on-Voice (WoV) | Technology that enables voice activation from a screen off, lower power state, to a screen on full power state. | +|WoV from Modern Standby| Wake-on-Voice from a Modern Standby (S0ix) screen off state to a screen on full power (S0) state. | +| Modern Standby | Windows Low Power Idle infrastructure - successor to Connected Standby (CS) in Windows 10. The first state of modern standby is when the screen is off. The deepest sleep state is when in DRIPS/Resiliency. For more information, see [Modern Standby](/windows-hardware/design/device-experiences/modern-standby).| +| KWS | Keyword spotter – the algorithm that provides the detection of "Hey Contoso". | | SW KWS | Software keyword spotter – an implementation of KWS that runs on the host (CPU). For "Hey Cortana", SW KWS is included as part of Windows. | -| HW KWS | Hardware keyword spotter – an implementation of KWS that runs offloaded on hardware | -| Burst buffer | A circular buffer used to store PCM data that can be bursted up in the event of a KWS detection, so that all audio that triggered a KWS detection is included | -| Event detector OEM Adapter | A user mode component that acts as an intermediary between the Windows voice assistant stack and driver | +| HW KWS | Hardware keyword spotter – an implementation of KWS that runs offloaded on hardware. | +| Burst buffer | A circular buffer used to store PCM data that can be bursted up in the event of a KWS detection, so that all audio that triggered a KWS detection is included. | +| Event detector OEM Adapter | A user mode component that acts as an intermediary between the Windows voice assistant stack and driver. | | Model | The acoustic model data file used by the KWS algorithm. The data file is static. Models are localized, one per locale.| -| MVA | Multiple Voice Agent - new HWKWS DDI which supports multiple agents | -| SVA | Single Voice Agent - previous HWKWS DDI which only supports a single agent (Cortana) | +| MVA | Multiple Voice Agent - HWKWS DDI which supports multiple agents. | +| SVA | Single Voice Agent - previous HWKWS DDI which only supports a single agent (Cortana). | ## Integrating a Hardware Keyword Spotter @@ -93,7 +94,7 @@ Validate HW support for [KSPROPSETID_SoundDetector2](kspropsetid-sounddetector2. ## Sample Code Overview -There is sample code for an audio driver that implements voice activation on GitHub as part of the SYSVAD virtual audio adapter sample. It is recommended to use [this code](https://github.com/Microsoft/Windows-driver-samples/tree/master/audio/sysvad/) as a starting point. +There is sample code for an audio driver that implements voice activation on GitHub as part of the SYSVAD virtual audio adapter sample. It is recommended to use [this code](https://github.com/Microsoft/Windows-driver-samples/tree/main/audio/sysvad/) as a starting point. For more information about the SYSVAD sample audio driver, see [Sample Audio Drivers](./sample-audio-drivers.md). @@ -105,13 +106,13 @@ The audio stack external interfaces for enabling Voice Activation serves as the - [*Event detector Device Driver Interface (DDI)*](/windows-hardware/drivers/ddi/eventdetectoroemadapter/nn-eventdetectoroemadapter-ieventdetectoroemadapter). The Event detector Device Driver Interface is responsible for configuring and arming the HW Keyword Spotter (KWS). It is also used by the driver to notify the system of a detection event. - [*IEvent Detector OEM Adapter DLL*](/windows-hardware/drivers/ddi/eventdetectoroemadapter/nn-eventdetectoroemadapter-ieventdetectoroemadapter). This DLL implements a COM interface to adapt the driver specific opaque data for use by the OS to assist with keyword detection. -- *WaveRT streaming enhancements*. The enhancements enable the audio driver to burst stream the buffered audio data from the keyword detection. +- [*WaveRT enhancements*](#wavert-enhancements). The enhancements enable the audio driver to burst stream the buffered audio data from the keyword detection. ### Audio Endpoint Properties Audio endpoint graph building occurs normally. The graph is prepared to handle faster than real time capture. Timestamps on captured buffers remain true. Specifically, the timestamps will correctly reflect data that was captured in the past and buffered, and is now bursting. -### Theory of Operation +### Theory of Bluetooth bypass audio streaming The driver exposes a KS filter for its capture device as usual. This filter supports several KS properties and a KS event to configure, enable and signal a detection event. The filter also includes an additional pin factory identified as a keyword spotter (KWS) pin. This pin is used to stream audio from the keyword spotter. @@ -187,7 +188,7 @@ Implement the following methods. ## WAVERT Enhancements -Miniport interfaces are defined to be implemented by WaveRT miniport drivers. These interfaces provide methods to either simplify the audio driver, improve OS audio pipeline performance and reliability, or support new scenarios. A new PnP device interface property is defined allowing the driver to provide a static expressions of its buffer size constraints to the OS. +Miniport interfaces are defined to be implemented by WaveRT miniport drivers. These interfaces provide methods to either simplify the audio driver, improve OS audio pipeline performance and reliability, or support new scenarios. A PnP device interface property is defined allowing the driver to provide a static expressions of its buffer size constraints to the OS. ### Buffer Sizes @@ -255,3 +256,119 @@ The audio stack is responsible for communicating the wake data (speaker ID, keyw ### Validation on Modern Standby Systems WoV from a system idle state can be validated on [Modern Standby](/windows-hardware/design/device-experiences/modern-standby) systems using the [Modern Standby Wake on Voice Basic Test on AC-power Source](/windows-hardware/test/hlk/testref/69df7cf2-6024-4eee-92ee-1506480614ee) and the [Modern Standby Wake on Voice Basic Test on DC-power Source](/windows-hardware/test/hlk/testref/614ffb93-eced-45ab-bf7b-e09291a97fd2) in the [HLK](/windows-hardware/test/hlk/). These tests check that the system has a hardware keyword spotter (HW-KWS), is able to enter the Deepest Runtime Idle Platform State (DRIPS) and is able to wake from Modern Standby on voice command with system resume latency of less than or equal to one second. + +## ACX and MVA + +Audio Class eXtension (ACX) defines a Windows Driver Framework (WDF) class extension for the audio domain. For more information about ACX, see [ACX audio class extensions overview](acx-audio-class-extensions-overview.md) and [Summary of ACX objects](acx-summary-of-objects.md). This section describes how to implement MVA using ACX. + +ACX uses the same KS infrastructure for the keyword spotter, adding a layer of abstraction to simplify driver implementation. With ACX the same OEM DLL is used as described above, and remains unchanged. Both ACX and Portcls require the [IEventDetectorOEMAdapter interface](/windows-hardware/drivers/ddi/eventdetectoroemadapter/nn-eventdetectoroemadapter-ieventdetectoroemadapter), and there's no difference in implementation between the two for the OEM adapter. + +The [AcxKeywordSpotterCreate function](/windows-hardware/drivers/ddi/acxelements/nf-acxelements-acxkeywordspottercreate) is used to create an ACX keyword spotter opaque object (ACXKEYWORDSPOTTER) that that will be associated with a circuit device object parent. + +The ACXKEYWORDSPOTTER object is used to replace all the KSPROPERTY_SOUNDDETECTOR calls, simplifying KWS implementation. It is used in the process of adding a KWS element and KWS pin to the ACX circuit. The associated callbacks take care of getting the patterns, arming, disarming and reset. It uses an initialized [ACX_KEYWORDSPOTTER_CONFIG structure](/windows-hardware/drivers/ddi/acxelements/ns-acxelements-acx_keywordspotter_config) that describes the configuration of the keyword spotter. + +The ACX_KEYWORDSPOTTER_CONFIG structure takes a [ACX_KEYWORDSPOTTER_CALLBACKS structure](/windows-hardware/drivers/ddi/acxelements/ns-acxelements-acx_keywordspotter_callbacks) that defines the following callbacks. + +EvtAcxKeywordSpotterRetrieveArm - The [ACX_KEYWORDSPOTTER_RETRIEVE_ARM](/windows-hardware/drivers/ddi/acxelements/nc-acxelements-evt_acx_keywordspotter_retrieve_arm) callback. + +EvtAcxKeywordSpotterAssignArm - The [ACX_KEYWORDSPOTTER_ASSIGN_ARM](/windows-hardware/drivers/ddi/acxelements/nc-acxelements-evt_acx_keywordspotter_assign_arm) callback. + +EvtAcxKeywordSpotterAssignPatterns - The [ACX_KEYWORDSPOTTER_ASSIGN_PATTERNS](/windows-hardware/drivers/ddi/acxelements/nc-acxelements-evt_acx_keywordspotter_assign_patterns) callback. + +EvtAcxKeywordSpotterAssignReset - The [ACX_KEYWORDSPOTTER_ASSIGN_RESET](/windows-hardware/drivers/ddi/acxelements/nc-acxelements-evt_acx_keywordspotter_assign_reset) callback. + +### ACX PNP Event + +The ACX PNP Event replaces KSNOTIFICATIONID_SoundDetector, simplifying the detection notification event. The [ACX_PNPEVENT_CONFIG_INIT function](/windows-hardware/drivers/ddi/acxevents/nf-acxevents-acx_pnpevent_config_init) initializes an [ACX_PNPEVENT_CONFIG structure](\windows-hardware/drivers/ddi/acxevents/ns-acxevents-acx_pnpevent_config). No inputs are used with this function. + +### ACX KWS Sample code + +The ACX KWS sample code shows the initialization of the callbacks, keyword elements and creation of the keyword spotter. + +```cpp +{ + NTSTATUS status; + WDF_OBJECT_ATTRIBUTES attributes; + ACX_KEYWORDSPOTTER_CALLBACKS keywordSpotterCallbacks; + ACX_KEYWORDSPOTTER_CONFIG keywordSpotterCfg; + PCODEC_KEYWORDSPOTTER_CONTEXT keywordSpotterCtx; + ACX_PNPEVENT_CONFIG keywordEventCfg; + ACXPNPEVENT keywordEvent; + + PAGED_CODE(); + + ACX_KEYWORDSPOTTER_CALLBACKS_INIT(&keywordSpotterCallbacks); + keywordSpotterCallbacks.EvtAcxKeywordSpotterRetrieveArm = CodecC_EvtAcxKeywordSpotterRetrieveArm; + keywordSpotterCallbacks.EvtAcxKeywordSpotterAssignArm = CodecC_EvtAcxKeywordSpotterAssignArm; + keywordSpotterCallbacks.EvtAcxKeywordSpotterAssignPatterns = CodecC_EvtAcxKeywordSpotterAssignPatterns; + keywordSpotterCallbacks.EvtAcxKeywordSpotterAssignReset = CodecC_EvtAcxKeywordSpotterAssignReset; + + ACX_KEYWORDSPOTTER_CONFIG_INIT(&keywordSpotterCfg); + keywordSpotterCfg.Pattern = &CONTOSO_KEYWORDCONFIGURATION_IDENTIFIER2; + keywordSpotterCfg.Callbacks = &keywordSpotterCallbacks; + + WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attributes, CODEC_KEYWORDSPOTTER_CONTEXT); + attributes.ParentObject = Circuit; +``` + +Next the [AcxKeywordSpotterCreate function](/windows-hardware/drivers/ddi/acxelements/nf-acxelements-acxkeywordspottercreate) is used to create the ACX keyword spotter object and associate it with an existing circuit. + +```cpp + status = AcxKeywordSpotterCreate(Circuit, &attributes, &keywordSpotterCfg, Element); + if (!NT_SUCCESS(status)) + { + ASSERT(FALSE); + goto exit; + } +``` + +Then the keyword spotter context is determined and used to create the KeywordDetector in NonPagedPoolNx memory. + +```cpp + + keywordSpotterCtx = GetCodecKeywordSpotterContext(*Element); + ASSERT(keywordSpotterCtx); + + keywordSpotterCtx->KeywordDetector = (PVOID) new(NonPagedPoolNx, DRIVER_TAG) CKeywordDetector(); + if (keywordSpotterCtx->KeywordDetector == NULL) + { + status = STATUS_INSUFFICIENT_RESOURCES; + ASSERT(FALSE); + goto exit; + } +``` + +In this sample code, the CKeywordDetector class that is added to the context is provided only as an example implementation which simulates keyword spotting within the sample driver. The CKeywordDetector class is not part of the ACX framework or a required part of implementation of MVA on ACX, but may provide a good starting point for development of an actual keyword spotter. + +Lastly, the ACX PnP Event is configured and created. + +```cpp + + ACX_PNPEVENT_CONFIG_INIT(&keywordEventCfg); + + WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attributes, CODEC_PNPEVENT_CONTEXT); + attributes.ParentObject = *Element; + status = AcxPnpEventCreate(Device, *Element, &attributes, &keywordEventCfg, &keywordEvent); + if (!NT_SUCCESS(status)) + { + ASSERT(FALSE); + goto exit; + } + + keywordSpotterCtx->Event = keywordEvent; + + // + // Done. + // + status = STATUS_SUCCESS; + +} +``` + +### Circuits with complex pin behavior including KWS + +For circuits with complex pin behavior such as circuits with host engine and/or KWS, the driver should disable ACX to from doing stream-bridge handling and instead, create a stream-bridge without inmode. This approach will prevent ACX from automatically associating streams to stream-bridges. + +## See also + +[Voice Activation](voice-activation.md) diff --git a/windows-driver-docs-pr/audio/voice-activation.md b/windows-driver-docs-pr/audio/voice-activation.md index e3a85be280..2f7a0e2882 100644 --- a/windows-driver-docs-pr/audio/voice-activation.md +++ b/windows-driver-docs-pr/audio/voice-activation.md @@ -1,13 +1,13 @@ --- title: Voice Activation description: Cortana, the Windows speech platform is used to power all of the speech experiences in Windows 10 such as Cortana and Dictation. -ms.date: 05/15/2020 +ms.date: 08/17/2023 --- # Voice Activation > [!NOTE] -> This topic refers primarily to our consumer experiences, which are currently delivered in Windows 10 (version 1909 and earlier). +> This topic refers primarily to our consumer experiences, which are currently delivered in Windows 10 (version 1909 and earlier) For more information, see [End of support for Cortana in Windows and Teams](https://support.microsoft.com/topic/end-of-support-for-cortana-in-windows-and-teams-d025b39f-ee5b-4836-a954-0ab646ee1efa). Cortana, the personal assistant technology was demonstrated for the first time at the Microsoft BUILD Developer Conference in 2013. The Windows speech platform is used to power all of the speech experiences in Windows 10 such as Cortana and Dictation. Voice activation is a feature that enables users to invoke a speech recognition engine from various device power states by saying a specific phrase - "Hey Cortana". To create hardware that supports voice activation technology, review the information in this topic. @@ -21,7 +21,6 @@ To understand the voice interaction experience available in Windows, review thes |Topic|Description| |----|----| | [What is Cortana?](https://support.microsoft.com/help/17214/cortana-what-is) | Provides and overview and usage direction for Cortana | -| [Make Cortana yours](https://support.microsoft.com/help/17178/windows-10-make-cortana-yours) | Describes customization available through Cortana's Settings screens. | ## Introduction to "Hey Cortana" Voice Activation and "Learn my voice" @@ -117,7 +116,7 @@ AEC Requirements for HW KWS There is sample code for an audio driver that implements voice activation on GitHub as part of the SYSVAD virtual audio adapter sample. It is recommended to use this code as a starting point. The code is available at this location. - + For more information about the SYSVAD sample audio driver, see [Sample Audio Drivers](sample-audio-drivers.md). @@ -135,7 +134,7 @@ The audio stack external interfaces for enabling Voice Activation serves as the Audio endpoint graph building occurs normally. The graph is prepared to handle faster than real time capture. Timestamps on captured buffers remain true. Specifically, the timestamps will correctly reflect data that was captured in the past and buffered, and is now “bursting”. -### Theory of Operation +### Theory of Bluetooth bypass audio streaming The driver exposes a KS filter for its capture device as usual. This filter supports several KS properties and a KS event to configure, enable and signal a detection event. The filter also includes an additional pin factory identified as a keyword spotter (KWS) pin. This pin is used to stream audio from the keyword spotter. diff --git a/windows-driver-docs-pr/audio/wdm-audio-support-in-different-versions-of-windows.md b/windows-driver-docs-pr/audio/wdm-audio-support-in-different-versions-of-windows.md index 31b50bdcf2..d120cc5d34 100644 --- a/windows-driver-docs-pr/audio/wdm-audio-support-in-different-versions-of-windows.md +++ b/windows-driver-docs-pr/audio/wdm-audio-support-in-different-versions-of-windows.md @@ -18,8 +18,6 @@ This section describes the operating system support for audio devices and driver ----------------------------------------------------------------------------------------------- -[Bluetooth Bypass Guidelines for Audio Drivers](bluetooth-bypass-guidelines-for-audio-drivers.md) - [Hardware-Offloaded Audio Processing](hardware-offloaded-audio-processing.md) [WDM Audio Platform Differences](wdm-audio-platform-differences.md) diff --git a/windows-driver-docs-pr/audio/windows-11-apis-for-audio-processing-objects.md b/windows-driver-docs-pr/audio/windows-11-apis-for-audio-processing-objects.md index f73f13a0ec..cddb42a20a 100644 --- a/windows-driver-docs-pr/audio/windows-11-apis-for-audio-processing-objects.md +++ b/windows-driver-docs-pr/audio/windows-11-apis-for-audio-processing-objects.md @@ -10,7 +10,7 @@ keywords: - Audio Settings, Audio Notifications - Windows 11 audio - CAPX, Core Audio Processing Object Extensions -ms.date: 07/08/2022 +ms.date: 08/11/2023 --- # Windows 11 APIs for Audio Processing Objects @@ -46,7 +46,7 @@ The latest versions of Windows, the WDK, and the SDK can be downloaded below thr Windows 11 WHCP Content has been updated to provide partners the means to validate these APIs. -The sample code for the content outlined in this topic can be found here: [Audio/SYSVAD/APO - github](https://github.com/microsoft/Windows-driver-samples/blob/master/audio/sysvad/APO/) +The sample code for the content outlined in this topic can be found here: [Audio/SYSVAD/APO - github](https://github.com/microsoft/Windows-driver-samples/blob/main/audio/sysvad/APO/) ## Acoustic Echo Cancellation (AEC) @@ -85,7 +85,7 @@ An APO can examine the APO_CONNECTION_PROPERTY.u32Signature field to determine w APO_CONNECTION_PROPERTY_SIGNATURE, while APO_CONNECTION_PROPERTY_V2 have a signature that equals APO_CONNECTION_PROPERTY_V2_SIGNATURE. If the signature has a value that equals APO_CONNECTION_PROPERTY_V2_SIGNATURE, the pointer to the APO_CONNECTION_PROPERTY structure may be safely typecast to an APO_CONNECTION_PROPERTY_V2 pointer. -The following code is from the [Aec APO MFX sample - AecApoMfx.cpp](https://github.com/microsoft/Windows-driver-samples/blob/master/audio/sysvad/APO/AecApo/AecApoMfx.cpp) and shows the recasting. +The following code is from the [Aec APO MFX sample - AecApoMfx.cpp](https://github.com/microsoft/Windows-driver-samples/blob/main/audio/sysvad/APO/AecApo/AecApoMfx.cpp) and shows the recasting. ```cpp if (ppInputConnections[0]->u32Signature == APO_CONNECTION_PROPERTY_V2_SIGNATURE) @@ -134,11 +134,11 @@ For more information, find additional information on the following pages. Refer to the following Sysvad Audio AecApo code samples. -- [Aec APO sample header - AecAPO.h](https://github.com/microsoft/Windows-driver-samples/blob/master/audio/sysvad/APO/AecApo/AecApo.h) +- [Aec APO sample header - AecAPO.h](https://github.com/microsoft/Windows-driver-samples/blob/main/audio/sysvad/APO/AecApo/AecApo.h) -- [Aec APO MFX sample - AecApoMfx.cpp](https://github.com/microsoft/Windows-driver-samples/blob/master/audio/sysvad/APO/AecApo/AecApoMfx.cpp) +- [Aec APO MFX sample - AecApoMfx.cpp](https://github.com/microsoft/Windows-driver-samples/blob/main/audio/sysvad/APO/AecApo/AecApoMfx.cpp) -The following code from the [Aec APO sample header- AecAPO.h](https://github.com/microsoft/Windows-driver-samples/blob/master/audio/sysvad/APO/AecApo/AecApo.h) shows the three new public methods being added. +The following code from the [Aec APO sample header- AecAPO.h](https://github.com/microsoft/Windows-driver-samples/blob/main/audio/sysvad/APO/AecApo/AecApo.h) shows the three new public methods being added. ```cpp public IApoAcousticEchoCancellation, @@ -187,7 +187,7 @@ The following code from the [Aec APO sample header- AecAPO.h](https://github.co ``` -The following code is from the [Aec APO MFX sample - AecApoMfx.cpp](https://github.com/microsoft/Windows-driver-samples/blob/master/audio/sysvad/APO/AecApo/AecApoMfx.cpp) and shows the implementation of AddAuxiliaryInput, when the APO can only handle one auxiliary input. +The following code is from the [Aec APO MFX sample - AecApoMfx.cpp](https://github.com/microsoft/Windows-driver-samples/blob/main/audio/sysvad/APO/AecApo/AecApoMfx.cpp) and shows the implementation of AddAuxiliaryInput, when the APO can only handle one auxiliary input. ```cpp @@ -249,6 +249,97 @@ This is the recommended buffer behavior for AEC. - On the call to IAudioProcessingObjectRT::APOProcess, the circular buffer should be read for the latest audio packet from the reference stream, and this packet should be used for running through the echo cancellation algorithm. - Timestamps on the reference and microphone data may be used to line up the speaker and mic data. +## Reference Loopback Stream + +By default, the loopback stream "taps into" (listens to) the audio stream prior to any volume or muting being applied. A loopback stream tapped before volume has been applied is known as a pre-volume loopback stream. An advantage of having a pre-volume loopback stream is a clear and uniform audio stream, regardless of the current volume setting. + +Some AEC algorithms may prefer obtaining a loopback stream that has been connected after any volume processing (including being muted). This configuration is known as post-volume loopback. + +In the next major version of Windows AEC APOs can request post-volume loopback on supported endpoints. + +### Limitations + +Unlike pre-volume loopback streams, which are available for all render endpoints, post-volume loopback streams may not be available on all endpoints. + +### Requesting Post-Volume Loopback + +AEC APOs that wish to use post-volume loopback should implement the [IApoAcousticEchoCancellation2](/windows/win32/api/audioenginebaseapo/nn-audioenginebaseapo-iapoacousticechocancellation2) interface. + +An AEC APO can request post-volume loopback by returning the **APO_REFERENCE_STREAM_PROPERTIES_POST_VOLUME_LOOPBACK** flag via the Properties parameter in its implementation of [IApoAcousticEchoCancellation2::GetDesiredReferenceStreamProperties](/windows/win32/api/audioenginebaseapo/nf-audioenginebaseapo-iapoacousticechocancellation2-getdesiredreferencestreamproperties). + +Depending on the render endpoint currently being used, post-volume loopback may not be available. An AEC APO is notified if post-volume loopback is being used when its [IApoAuxiliaryInputConfiguration::AddAuxiliaryInput](/windows/win32/api/audioenginebaseapo/nf-audioenginebaseapo-iapoauxiliaryinputconfiguration-addauxiliaryinput) method is called. If the [AcousticEchoCanceller_Reference_Input](/windows/win32/api/audioengineextensionapo/ns-audioengineextensionapo-acousticechocanceller_reference_input) streamProperties field contains **APO_REFERENCE_STREAM_PROPERTIES_POST_VOLUME_LOOPBACK**, post-volume loopback is in use. + +The following code from the AEC APO sample header- AecAPO.h shows the three new public methods being added. + +```cpp +public: + // IApoAcousticEchoCancellation2 + STDMETHOD(GetDesiredReferenceStreamProperties)( + _Out_ APO_REFERENCE_STREAM_PROPERTIES * properties) override; + + // IApoAuxiliaryInputConfiguration + STDMETHOD(AddAuxiliaryInput)( + DWORD dwInputId, + UINT32 cbDataSize, + _In_ BYTE* pbyData, + _In_ APO_CONNECTION_DESCRIPTOR *pInputConnection + ) override; +``` + +The following code snippet is from the AEC APO MFX sample - AecApoMfx.cpp and shows the implementation of GetDesiredReferenceStreamProperties, and relevant portion of AddAuxiliaryInput. + +```cpp +STDMETHODIMP SampleApo::GetDesiredReferenceStreamProperties( + _Out_ APO_REFERENCE_STREAM_PROPERTIES * properties) +{ + RETURN_HR_IF_NULL(E_INVALIDARG, properties); + + // Always request that a post-volume loopback stream be used, if + // available. We will find out which type of stream was actually + // created when AddAuxiliaryInput is invoked. + *properties = APO_REFERENCE_STREAM_PROPERTIES_POST_VOLUME_LOOPBACK; + return S_OK; +} + +STDMETHODIMP +CAecApoMFX::AddAuxiliaryInput( + DWORD dwInputId, + UINT32 cbDataSize, + BYTE *pbyData, + APO_CONNECTION_DESCRIPTOR * pInputConnection +) +{ + // Parameter checking skipped for brevity, please see sample for + // full implementation. + + AcousticEchoCanceller_Reference_Input* referenceInput = nullptr; + APOInitSystemEffects3* papoSysFxInit3 = nullptr; + + if (cbDataSize == sizeof(AcousticEchoCanceller_Reference_Input)) + { + referenceInput = + reinterpret_cast(pbyData); + + if (WI_IsFlagSet( + referenceInput->streamProperties, + APO_REFERENCE_STREAM_PROPERTIES_POST_VOLUME_LOOPBACK)) + { + // Post-volume loopback is being used. + m_bUsingPostVolumeLoopback = TRUE; + + // Note that we can get to the APOInitSystemEffects3 from + // AcousticEchoCanceller_Reference_Input. + papoSysFxInit3 = (APOInitSystemEffects3*)pbyData; + } + else if (cbDataSize == sizeof(APOInitSystemEffects3)) + { + // Post-volume loopback is not supported. + papoSysFxInit3 = (APOInitSystemEffects3*)pbyData; + } + + // Remainder of method skipped for brevity. +``` + ## Settings Framework The Settings Framework allows APOs to expose methods for querying and modifying the property store for audio effects ("FX Property Store") on an audio endpoint. This framework can be used by APOs and by Hardware Support Apps (HSA) that wish to communicate settings to that APO. HSAs can be Universal Windows Platform (UWP) apps and require a special capability to invoke the APIs in the Settings Framework. For more information about HSA apps, see [UWP device apps](../devapps/index.md). @@ -614,7 +705,7 @@ STDMETHODIMP PropertyChangeNotificationClient::OnPropertyChanged(AUDIO_SYSTEMEFF ### Sample code - Settings Framework -This sample code is from the sysvad [SFX Swap APO sample - SwapAPOSFX.cpp](https://github.com/microsoft/Windows-driver-samples/blob/master/audio/sysvad/APO/SwapAPO/swapaposfx.cpp#L300-L329). +This sample code is from the sysvad [SFX Swap APO sample - SwapAPOSFX.cpp](https://github.com/microsoft/Windows-driver-samples/blob/main/audio/sysvad/APO/SwapAPO/swapaposfx.cpp#L300-L329). ```cpp // SampleApo supports the new IAudioSystemEffects3 interface so it will receive APOInitSystemEffects3 @@ -845,7 +936,7 @@ STDMETHODIMP_(void) SampleApo::HandleNotification(_In_ APO_NOTIFICATION* apoNoti } ``` -The following code is from the [Swap APO MFX sample - swapapomfx.cpp](https://github.com/microsoft/Windows-driver-samples/blob/master/audio/sysvad/APO/SwapAPO/swapapomfx.cpp#L770-L794) and shows registering for events, by returning an array of APO_NOTIFICATION_DESCRIPTORs. +The following code is from the [Swap APO MFX sample - swapapomfx.cpp](https://github.com/microsoft/Windows-driver-samples/blob/main/audio/sysvad/APO/SwapAPO/swapapomfx.cpp#L770-L794) and shows registering for events, by returning an array of APO_NOTIFICATION_DESCRIPTORs. ```cpp HRESULT CSwapAPOMFX::GetApoNotificationRegistrationInfo(_Out_writes_(*count) APO_NOTIFICATION_DESCRIPTOR **apoNotifications, _Out_ DWORD *count) @@ -875,7 +966,7 @@ HRESULT CSwapAPOMFX::GetApoNotificationRegistrationInfo(_Out_writes_(*count) APO } ``` -The following code is from the [SwapAPO MFX HandleNotifications sample - swapapomfx.cpp](https://github.com/microsoft/Windows-driver-samples/blob/master/audio/sysvad/APO/SwapAPO/swapapomfx.cpp#L796-L827) and shows how to handle notifications. +The following code is from the [SwapAPO MFX HandleNotifications sample - swapapomfx.cpp](https://github.com/microsoft/Windows-driver-samples/blob/main/audio/sysvad/APO/SwapAPO/swapapomfx.cpp#L796-L827) and shows how to handle notifications. ```cpp void CSwapAPOMFX::HandleNotification(APO_NOTIFICATION *apoNotification) @@ -924,7 +1015,9 @@ IMPLEMENT_TRACELOGGING_CLASS(ApoTelemetryProvider, "Microsoft.Windows.Audio.ApoT (0x8b4a0b51, 0x5dcf, 0x5a9c, 0x28, 0x17, 0x95, 0xd0, 0xec, 0x87, 0x6a, 0x87)); ``` -Each APO has its own activity ID. The trace logging events are not marked as telemetry. Registry settings are available to log events to a file for use during development of an APO. Since this does not use the existing trace logging mechanism, existing console tools can be used to filter for these events and display them in real-time. +Each APO has its own activity ID. Since this uses the existing trace logging mechanism, existing console tools can be used to filter for these events and display them in real-time. You can use existing tools like tracelog and tracefmt as described in [Tools for Software Tracing - Windows drivers](../devtest/tools-for-software-tracing.md). For more information on trace sessions, see [Creating a Trace Session with a Control GUID](../devtest/creating-a-trace-session-with-a-control-guid.md). + +The trace logging events are not marked as telemetry and will not be displayed as a telemetry provider in tools such as xperf. ### Implementation - Logging Framework @@ -940,7 +1033,7 @@ For more information, see [IAudioProcessingObjectLoggingService](/windows/win32/ The sample demonstrates the use of the method IAudioProcessingObjectLoggingService::ApoLog and how this interface pointer is obtained in IAudioProcessingObject::Initialize. -[AecApoMfx Logging Example](https://github.com/microsoft/Windows-driver-samples/blob/master/audio/sysvad/APO/AecApo/AecApoMfx.cpp#L306-L310). +[AecApoMfx Logging Example](https://github.com/microsoft/Windows-driver-samples/blob/main/audio/sysvad/APO/AecApo/AecApoMfx.cpp#L306-L310). @@ -1116,9 +1209,9 @@ STDMETHODIMP SampleApo3AsyncCallback::Invoke(_In_ IRtwqAsyncResult* asyncResult) ``` For more examples of how to utilize this interface, please see the following sample code: -- [SwapAPO SwapMFXApoAsyncCallback Class Definition - Example](https://github.com/microsoft/Windows-driver-samples/blob/master/audio/sysvad/APO/SwapAPO/SwapAPO.h#L48-L75) -- [SwapAPO Invoke Function - Example](https://github.com/microsoft/Windows-driver-samples/blob/master/audio/sysvad/APO/SwapAPO/swapapomfx.cpp#L124-L141) -- [SwapAPO Create Async Callback - Example](https://github.com/microsoft/Windows-driver-samples/blob/master/audio/sysvad/APO/SwapAPO/swapapomfx.cpp#L347-L366) +- [SwapAPO SwapMFXApoAsyncCallback Class Definition - Example](https://github.com/microsoft/Windows-driver-samples/blob/main/audio/sysvad/APO/SwapAPO/SwapAPO.h#L48-L75) +- [SwapAPO Invoke Function - Example](https://github.com/microsoft/Windows-driver-samples/blob/main/audio/sysvad/APO/SwapAPO/swapapomfx.cpp#L124-L141) +- [SwapAPO Create Async Callback - Example](https://github.com/microsoft/Windows-driver-samples/blob/main/audio/sysvad/APO/SwapAPO/swapapomfx.cpp#L347-L366) ## Audio Effects Discovery and Control for Effects @@ -1137,9 +1230,9 @@ An APO needs to implement the [IAudioSystemEffects3](/windows/win32/api/audioeng ### Sample code - Audio Effect Discovery -The Audio Effect Discovery sample code can be found within the [SwapAPOSFX sample - swapaposfx.cpp](https://github.com/microsoft/Windows-driver-samples/blob/master/audio/sysvad/APO/SwapAPO/swapaposfx.cpp). +The Audio Effect Discovery sample code can be found within the [SwapAPOSFX sample - swapaposfx.cpp](https://github.com/microsoft/Windows-driver-samples/blob/main/audio/sysvad/APO/SwapAPO/swapaposfx.cpp). -The following sample code illustrates how to retrieve the list of configurable effects. [GetControllableSystemEffectsList sample - swapaposfx.cpp](https://github.com/microsoft/Windows-driver-samples/blob/master/audio/sysvad/APO/SwapAPO/swapaposfx.cpp#L583-L625) +The following sample code illustrates how to retrieve the list of configurable effects. [GetControllableSystemEffectsList sample - swapaposfx.cpp](https://github.com/microsoft/Windows-driver-samples/blob/main/audio/sysvad/APO/SwapAPO/swapaposfx.cpp#L583-L625) ```cpp HRESULT CSwapAPOSFX::GetControllableSystemEffectsList(_Outptr_result_buffer_maybenull_(*numEffects) AUDIO_SYSTEMEFFECT** effects, _Out_ UINT* numEffects, _In_opt_ HANDLE event) @@ -1187,7 +1280,7 @@ HRESULT CSwapAPOSFX::GetControllableSystemEffectsList(_Outptr_result_buffer_mayb } ``` -The following sample code illustrates how to enable and disable effects. [SetAudioSystemEffectState sample - swapaposfx.cpp](https://github.com/microsoft/Windows-driver-samples/blob/master/audio/sysvad/APO/SwapAPO/swapaposfx.cpp#L627-L653) +The following sample code illustrates how to enable and disable effects. [SetAudioSystemEffectState sample - swapaposfx.cpp](https://github.com/microsoft/Windows-driver-samples/blob/main/audio/sysvad/APO/SwapAPO/swapaposfx.cpp#L627-L653) ```cpp HRESULT CSwapAPOSFX::SetAudioSystemEffectState(GUID effectId, AUDIO_SYSTEMEFFECT_STATE state) diff --git a/windows-driver-docs-pr/audio/windows-default-apos.md b/windows-driver-docs-pr/audio/windows-default-apos.md index 1e7c360621..0dd6745e71 100644 --- a/windows-driver-docs-pr/audio/windows-default-apos.md +++ b/windows-driver-docs-pr/audio/windows-default-apos.md @@ -11,7 +11,7 @@ ms.date: 11/07/2018 # Windows Default APOs -With Windows Vista the audio driver does not provide digital audio system effects. All digital signal processing for creating system effects is provided by real-time in-process COM objects called system effects audio processing objects (APOs). +With Windows the audio driver does not provide digital audio system effects. All digital signal processing for creating system effects is provided by real-time in-process COM objects called system effects audio processing objects (APOs). Windows provides an **Enhancements** tab with the Sound applet on the Control Panel for configuring these system effects. The APOs provided by default with Windows are shown in the following list. diff --git a/windows-driver-docs-pr/battery/adddevice-routine-of-a-battery-miniclass-driver.md b/windows-driver-docs-pr/battery/adddevice-routine-of-a-battery-miniclass-driver.md index 88e29a7a02..b9c8e1833b 100644 --- a/windows-driver-docs-pr/battery/adddevice-routine-of-a-battery-miniclass-driver.md +++ b/windows-driver-docs-pr/battery/adddevice-routine-of-a-battery-miniclass-driver.md @@ -9,19 +9,12 @@ ms.date: 04/20/2017 # AddDevice Routine of a Battery Miniclass Driver - -## - - Every battery miniclass driver must have an [*AddDevice*](/windows-hardware/drivers/ddi/wdm/nc-wdm-driver_add_device) routine, which initializes battery-specific state. The PnP Manager calls the *AddDevice* routine for each battery device controlled by this miniclass driver. In addition to the tasks required of a PnP *AddDevice* routine, the *AddDevice* routine for a battery miniclass driver must also do the following: -1. Create an FDO for the battery and attach the FDO to the device stack for the controller. - -2. Initialize the [**BATTERY\_MINIPORT\_INFO**](/windows/win32/api/batclass/ns-batclass-battery_miniport_info) structure and call [**BatteryClassInitializeDevice**](/windows/win32/api/batclass/nf-batclass-batteryclassinitializedevice) to register the miniclass driver with the battery class driver. - -3. Perform any other initialization required for the device. +1. Create an FDO for the battery and attach the FDO to the device stack for the controller. - +2. Initialize the [**BATTERY\_MINIPORT\_INFO**](/windows/win32/api/batclass/ns-batclass-battery_miniport_info) structure and call [**BatteryClassInitializeDevice**](/windows/win32/api/batclass/nf-batclass-batteryclassinitializedevice) to register the miniclass driver with the battery class driver. +3. Perform any other initialization required for the device. diff --git a/windows-driver-docs-pr/battery/battery-class-driver-functionality.md b/windows-driver-docs-pr/battery/battery-class-driver-functionality.md index 16ead5950a..f18ba221ec 100644 --- a/windows-driver-docs-pr/battery/battery-class-driver-functionality.md +++ b/windows-driver-docs-pr/battery/battery-class-driver-functionality.md @@ -8,27 +8,20 @@ ms.date: 04/20/2017 # Battery Class Driver Functionality - -## - - The kernel-mode battery class driver, battc.sys, provides device-independent battery support and exports support routines for use by all device-specific battery miniclass drivers. The battery class driver takes care of the following tasks for miniclass drivers: -- Performing a large part of miniclass driver initialization, including allocating system resources and space for the miniclass driver's class data +- Performing a large part of miniclass driver initialization, including allocating system resources and space for the miniclass driver's class data -- Handling device control IRPs ([**IRP\_MJ\_DEVICE\_CONTROL**](../kernel/irp-mj-device-control.md)) that specify battery class IOCTLs. (See the Microsoft Windows SDK for information about these IOCTLs.) +- Handling device control IRPs ([**IRP\_MJ\_DEVICE\_CONTROL**](../kernel/irp-mj-device-control.md)) that specify battery class IOCTLs. (See the Microsoft Windows SDK for information about these IOCTLs.) -- Serializing requests to the battery device +- Serializing requests to the battery device -- Administering DC power policy for the operating system +- Administering DC power policy for the operating system -- Freeing system resources if the miniclass driver is unloaded +- Freeing system resources if the miniclass driver is unloaded -- Handling certain standard battery WMI classes +- Handling certain standard battery WMI classes See [Battery Miniclass Driver Routines](/windows-hardware/drivers/ddi/_battery/) for descriptions of the routines that the battery class driver exports to battery miniclass drivers. - - - diff --git a/windows-driver-docs-pr/battery/battery-miniclass-driver-functionality.md b/windows-driver-docs-pr/battery/battery-miniclass-driver-functionality.md index f83c92769e..09156c2d28 100644 --- a/windows-driver-docs-pr/battery/battery-miniclass-driver-functionality.md +++ b/windows-driver-docs-pr/battery/battery-miniclass-driver-functionality.md @@ -8,27 +8,20 @@ ms.date: 04/20/2017 # Battery Miniclass Driver Functionality - -## - - A battery miniclass driver is responsible for the following: -- Creating an FDO for its devices and storing device-specific information in the associated device extension +- Creating an FDO for its devices and storing device-specific information in the associated device extension -- Assigning and maintaining the battery tag for the current battery +- Assigning and maintaining the battery tag for the current battery -- Keeping track of battery capacity, charge, and power state +- Keeping track of battery capacity, charge, and power state -- Responding to requests from the class driver for battery status information +- Responding to requests from the class driver for battery status information -- Notifying the battery class driver when the power state of the battery changes +- Notifying the battery class driver when the power state of the battery changes -- Charging or discharging a specific battery when requested +- Charging or discharging a specific battery when requested A battery miniclass driver calls the battery class driver's support routines for other operations, such as handling IOCTLs, as described in [Battery Class Driver Functionality](battery-class-driver-functionality.md). Every battery miniclass driver provides a set of [BatteryMini*Xxx*](/windows-hardware/drivers/ddi/_battery/) routines. The battery class driver calls these routines to request that the miniclass driver perform device-specific tasks. In addition, the miniclass driver must have other routines, as described in [Supplying Required Battery Miniclass Driver Functionality](supplying-required-battery-miniclass-driver-functionality.md). - - - diff --git a/windows-driver-docs-pr/battery/creating-an-fdo-in-the-battery-miniclass-driver.md b/windows-driver-docs-pr/battery/creating-an-fdo-in-the-battery-miniclass-driver.md index 0ea2db382f..4b1b7cf846 100644 --- a/windows-driver-docs-pr/battery/creating-an-fdo-in-the-battery-miniclass-driver.md +++ b/windows-driver-docs-pr/battery/creating-an-fdo-in-the-battery-miniclass-driver.md @@ -10,13 +10,9 @@ ms.date: 04/20/2017 # Creating an FDO in the Battery Miniclass Driver - -## - - The miniclass driver should create an FDO and attach it to the device stack for the device, as follows: -1. Call [**IoCreateDevice**](/windows-hardware/drivers/ddi/wdm/nf-wdm-iocreatedevice) to create an FDO for the current device, as follows: +1. Call [**IoCreateDevice**](/windows-hardware/drivers/ddi/wdm/nf-wdm-iocreatedevice) to create an FDO for the current device, as follows: ```cpp Status = IoCreateDevice( @@ -32,7 +28,7 @@ The miniclass driver should create an FDO and attach it to the device stack for The input parameters to [**IoCreateDevice**](/windows-hardware/drivers/ddi/wdm/nf-wdm-iocreatedevice) are a pointer to the driver object that was passed to the *AddDevice* routine, the size of the device extension, NULL in place of a device name, and the system-defined device type (FILE\_DEVICE\_BATTERY). Battery miniclass drivers can specify zero for the *DeviceCharacteristics* parameter, which is irrelevant to these drivers. More than one thread can send I/O requests to the battery, so the miniclass driver passes FALSE as the *Exclusive* parameter. **IoCreateDevice** returns a pointer to the created FDO. -2. In the returned FDO, set flags and the stack size. For example: +2. In the returned FDO, set flags and the stack size. For example: ```cpp Fdo->Flags |= DO_BUFFERED_IO; @@ -42,7 +38,7 @@ The miniclass driver should create an FDO and attach it to the device stack for Setting the DO\_BUFFERED\_IO flag allows the miniclass driver to use buffered I/O for IRPs. Setting the DO\_POWER\_PAGABLE flag indicates that the driver is pageable and prevents it from getting power IRPs at IRQL >= DISPATCH\_LEVEL. Finally, because battery IRPs require an additional stack location, miniclass drivers should set **StackSize** to the PDO stack size plus two, so that the driver can pass the IRP down to the PDO. -3. Store the pointer to the device's PDO, the pointer to the FDO, the device type, the device name, and any other necessary state in the device extension. For example: +3. Store the pointer to the device's PDO, the pointer to the FDO, the device type, the device name, and any other necessary state in the device extension. For example: ```cpp NewBatt = (PNEW_BATT) Fdo->DeviceExtension; @@ -56,7 +52,7 @@ The miniclass driver should create an FDO and attach it to the device stack for You determine the information stored in the device extension. For example, a smart battery driver might retain the number of batteries, a Boolean value indicating whether a battery selector is present, and, optionally, information about that battery selector. -4. Call [**IoAttachDeviceToDeviceStack**](/windows-hardware/drivers/ddi/wdm/nf-wdm-ioattachdevicetodevicestack) to attach the FDO to the device stack, then store the returned pointer, as follows: +4. Call [**IoAttachDeviceToDeviceStack**](/windows-hardware/drivers/ddi/wdm/nf-wdm-ioattachdevicetodevicestack) to attach the FDO to the device stack, then store the returned pointer, as follows: ```cpp NewBatt->LowerDO = IoAttachDeviceToDeviceStack(Fdo,Pdo); @@ -64,13 +60,10 @@ The miniclass driver should create an FDO and attach it to the device stack for The call returns a pointer to the next-lower device object, which this example stores in the device extension. -5. Clear the DO\_DEVICE\_INITIALIZING flag in the FDO, as follows: +5. Clear the DO\_DEVICE\_INITIALIZING flag in the FDO, as follows: ```cpp Fdo->Flags &= ~DO_DEVICE_INITIALIZING; ``` Clearing the DO\_DEVICE\_INITIALIZING flag allows the device object to be opened subsequently by components higher in the device stack. - - - diff --git a/windows-driver-docs-pr/battery/dispatchdevicecontrol-routine-of-a-battery-miniclass-driver.md b/windows-driver-docs-pr/battery/dispatchdevicecontrol-routine-of-a-battery-miniclass-driver.md index 92b9325d85..738d621e3f 100644 --- a/windows-driver-docs-pr/battery/dispatchdevicecontrol-routine-of-a-battery-miniclass-driver.md +++ b/windows-driver-docs-pr/battery/dispatchdevicecontrol-routine-of-a-battery-miniclass-driver.md @@ -10,19 +10,15 @@ ms.date: 04/20/2017 # DispatchDeviceControl Routine of a Battery Miniclass Driver - -## - - The power manager sends device control IRPs (IRP\_MJ\_DEVICE\_CONTROL) to the miniclass drivers through the composite battery driver. The [*DispatchDeviceControl*](/windows-hardware/drivers/ddi/wdm/nc-wdm-driver_dispatch) routine in the battery miniclass driver handles IRPs that contain battery IOCTLs. In [*DispatchDeviceControl*](/windows-hardware/drivers/ddi/wdm/nc-wdm-driver_dispatch), the miniclass driver can call the class driver's [**BatteryClassIoctl**](/windows/win32/api/batclass/nf-batclass-batteryclassioctl) routine to perform any system-defined device control tasks; **BatteryClassIoctl** handles device control IOCTLs for batteries. The [*DispatchDeviceControl*](/windows-hardware/drivers/ddi/wdm/nc-wdm-driver_dispatch) routine should do the following: -1. If the miniclass driver defines any private IOCTLs, determine whether the current IOCTL is among them. If so, perform the requested operation, complete the IRP, specifying IO\_NO\_INCREMENT, and go to step 4. +1. If the miniclass driver defines any private IOCTLs, determine whether the current IOCTL is among them. If so, perform the requested operation, complete the IRP, specifying IO\_NO\_INCREMENT, and go to step 4. -2. If the IOCTL is not a private IOCTL defined by the miniclass driver, call **BatteryClassIoctl**, passing the IRP and the class handle returned by [**BatteryClassInitializeDevice**](/windows/win32/api/batclass/nf-batclass-batteryclassinitializedevice). For example: +2. If the IOCTL is not a private IOCTL defined by the miniclass driver, call **BatteryClassIoctl**, passing the IRP and the class handle returned by [**BatteryClassInitializeDevice**](/windows/win32/api/batclass/nf-batclass-batteryclassinitializedevice). For example: ```cpp Status = BatteryClassIoctl (NewBattNP->ClassHandle, Irp); @@ -30,9 +26,6 @@ The [*DispatchDeviceControl*](/windows-hardware/drivers/ddi/wdm/nc-wdm-driver_di The class driver's [**BatteryClassIoctl**](/windows/win32/api/batclass/nf-batclass-batteryclassioctl)routine determines whether the IOCTL is intended for the specified battery. If so, it calls the corresponding [BatteryMini*Xxx*](/windows-hardware/drivers/ddi/_battery/) routine to satisfy the request and then completes the IRP, returning STATUS\_SUCCESS. Otherwise, it returns STATUS\_NOT\_SUPPORTED. -3. If [**BatteryClassIoctl**](/windows/win32/api/batclass/nf-batclass-batteryclassioctl) returns STATUS\_NOT\_SUPPORTED, indicating that this is not a battery IRP, pass the IRP to the next-lower driver. - -4. Pass the returned status as its own function return value. - - +3. If [**BatteryClassIoctl**](/windows/win32/api/batclass/nf-batclass-batteryclassioctl) returns STATUS\_NOT\_SUPPORTED, indicating that this is not a battery IRP, pass the IRP to the next-lower driver. +4. Pass the returned status as its own function return value. diff --git a/windows-driver-docs-pr/battery/dispatchsystemcontrol-routine-of-a-battery-miniclass-driver.md b/windows-driver-docs-pr/battery/dispatchsystemcontrol-routine-of-a-battery-miniclass-driver.md index 1020c8cf37..a984de26ab 100644 --- a/windows-driver-docs-pr/battery/dispatchsystemcontrol-routine-of-a-battery-miniclass-driver.md +++ b/windows-driver-docs-pr/battery/dispatchsystemcontrol-routine-of-a-battery-miniclass-driver.md @@ -10,10 +10,6 @@ ms.date: 04/20/2017 # DispatchSystemControl Routine of a Battery Miniclass Driver - -## - - Battery miniclass drivers must support [Windows Management Instrumentation](../kernel/implementing-wmi.md) (WMI) by supplying a [*DispatchSystemControl*](/windows-hardware/drivers/ddi/wdm/nc-wdm-driver_dispatch) routine to handle the [**IRP\_MJ\_SYSTEM\_CONTROL**](../kernel/irp-mj-system-control.md) IRP. WMI provides a uniform way for drivers to expose measurement and instrumentation data. Battery miniclass drivers use the [**BatteryClassSystemControl**](/windows/win32/api/batclass/nf-batclass-batteryclasssystemcontrol) routine to do initial processing. **BatteryClassSystemControl** takes a *WmiLibContext* parameter, which specifies a dispatch table of functions. The routine uses the **MinorFunction** member of IRP\_MJ\_SYSTEM\_CONTROL to determine which dispatch function it calls. @@ -24,5 +20,3 @@ Inside its [**DpWmiQueryDataBlock**](/windows-hardware/drivers/ddi/wmilib/nc-wmi Battery miniclass drivers are not required to do any WMI IRP processing beyond calling **BatteryClassQueryWmiDataBlock**. In a minimal implementation of WMI handling for a battery miniclass driver, if **BatteryClassQueryWmiDataBlock** returns STATUS\_WMI\_GUID\_NOT\_FOUND, the miniclass driver simply calls [**WmiCompleteRequest**](/windows-hardware/drivers/ddi/wmilib/nf-wmilib-wmicompleterequest) with a status value of STATUS\_WMI\_GUID\_NOT\_FOUND. - - diff --git a/windows-driver-docs-pr/battery/driverentry-routine-of-a-battery-miniclass-driver.md b/windows-driver-docs-pr/battery/driverentry-routine-of-a-battery-miniclass-driver.md index eb7d1fa5cc..44fe2c9cd3 100644 --- a/windows-driver-docs-pr/battery/driverentry-routine-of-a-battery-miniclass-driver.md +++ b/windows-driver-docs-pr/battery/driverentry-routine-of-a-battery-miniclass-driver.md @@ -9,29 +9,25 @@ ms.date: 04/20/2017 # DriverEntry Routine of a Battery Miniclass Driver - -## - - The [*DriverEntry*](/windows-hardware/drivers/ddi/wdm/nc-wdm-driver_initialize) routine initializes the miniclass driver. The miniclass driver's [*DriverEntry*](/windows-hardware/drivers/ddi/wdm/nc-wdm-driver_initialize) routine sets up the following driver-specific entry points: -- The [*Unload*](/windows-hardware/drivers/ddi/wdm/nc-wdm-driver_unload) routine in *DriverObject*->**DriverUnload** +- The [*Unload*](/windows-hardware/drivers/ddi/wdm/nc-wdm-driver_unload) routine in *DriverObject*->**DriverUnload** -- The driver's [*AddDevice*](/windows-hardware/drivers/ddi/wdm/nc-wdm-driver_add_device) routine in *DriverObject*->**DriverExtension**->**AddDevice** +- The driver's [*AddDevice*](/windows-hardware/drivers/ddi/wdm/nc-wdm-driver_add_device) routine in *DriverObject*->**DriverExtension**->**AddDevice** -- The [*DRIVER_DISPATCH*](/windows-hardware/drivers/ddi/wdm/nc-wdm-driver_dispatch) callback function in *DriverObject*->**MajorFunction**\[[**IRP\_MJ\_POWER**](../kernel/irp-mj-power.md)\] +- The [*DRIVER_DISPATCH*](/windows-hardware/drivers/ddi/wdm/nc-wdm-driver_dispatch) callback function in *DriverObject*->**MajorFunction**\[[**IRP\_MJ\_POWER**](../kernel/irp-mj-power.md)\] -- The [*DRIVER_DISPATCH*](/windows-hardware/drivers/ddi/wdm/nc-wdm-driver_dispatch) callback function in *DriverObject*->**MajorFunction**\[[**IRP\_MJ\_PNP**](../kernel/irp-mj-pnp.md)\] +- The [*DRIVER_DISPATCH*](/windows-hardware/drivers/ddi/wdm/nc-wdm-driver_dispatch) callback function in *DriverObject*->**MajorFunction**\[[**IRP\_MJ\_PNP**](../kernel/irp-mj-pnp.md)\] -- The [*DRIVER_DISPATCH*](/windows-hardware/drivers/ddi/wdm/nc-wdm-driver_dispatch) callback function in *DriverObject*->**MajorFunction**\[[**IRP\_MJ\_CREATE**](../kernel/irp-mj-create.md)\] +- The [*DRIVER_DISPATCH*](/windows-hardware/drivers/ddi/wdm/nc-wdm-driver_dispatch) callback function in *DriverObject*->**MajorFunction**\[[**IRP\_MJ\_CREATE**](../kernel/irp-mj-create.md)\] -- The [*DRIVER_DISPATCH*](/windows-hardware/drivers/ddi/wdm/nc-wdm-driver_dispatch) callback function in *DriverObject*->**MajorFunction**\[[**IRP\_MJ\_CLOSE**](../kernel/irp-mj-close.md)\] +- The [*DRIVER_DISPATCH*](/windows-hardware/drivers/ddi/wdm/nc-wdm-driver_dispatch) callback function in *DriverObject*->**MajorFunction**\[[**IRP\_MJ\_CLOSE**](../kernel/irp-mj-close.md)\] -- The [*DRIVER_DISPATCH*](/windows-hardware/drivers/ddi/wdm/nc-wdm-driver_dispatch) callback function in *DriverObject*->**MajorFunction**\[[**IRP\_MJ\_DEVICE\_CONTROL**](../kernel/irp-mj-device-control.md)\] +- The [*DRIVER_DISPATCH*](/windows-hardware/drivers/ddi/wdm/nc-wdm-driver_dispatch) callback function in *DriverObject*->**MajorFunction**\[[**IRP\_MJ\_DEVICE\_CONTROL**](../kernel/irp-mj-device-control.md)\] -- The [*DRIVER_DISPATCH*](/windows-hardware/drivers/ddi/wdm/nc-wdm-driver_dispatch) callback function in *DriverObject*->**MajorFunction**\[[**IRP\_MJ\_SYSTEM\_CONTROL**](../kernel/irp-mj-system-control.md)\]. +- The [*DRIVER_DISPATCH*](/windows-hardware/drivers/ddi/wdm/nc-wdm-driver_dispatch) callback function in *DriverObject*->**MajorFunction**\[[**IRP\_MJ\_SYSTEM\_CONTROL**](../kernel/irp-mj-system-control.md)\]. The following sample code initializes these entry points for a hypothetical NewBatt miniclass driver: @@ -65,6 +61,3 @@ For additional routine-specific requirements, see the following topics: [*DRIVER_DISPATCH*](/windows-hardware/drivers/ddi/wdm/nc-wdm-driver_dispatch) [*DispatchClose*](/windows-hardware/drivers/ddi/wdm/nc-wdm-driver_dispatch) - - - diff --git a/windows-driver-docs-pr/battery/index.md b/windows-driver-docs-pr/battery/index.md index c9c9d96eef..2aed3c28e8 100644 --- a/windows-driver-docs-pr/battery/index.md +++ b/windows-driver-docs-pr/battery/index.md @@ -8,10 +8,6 @@ ms.topic: article # Battery Devices Design Guide - -## - - A battery typically has a pair of drivers: the generic battery class driver that Microsoft provides, and a miniclass driver written specifically for that individual type of battery. The class driver defines the overall functionality of the batteries in the system and interacts with the power manager. @@ -19,11 +15,3 @@ The class driver defines the overall functionality of the batteries in the syste This design guide focuses on [Writing Battery Miniclass Drivers](writing-battery-miniclass-drivers.md). In addition this section includes information on [Writing UPS Minidrivers](writing-ups-minidrivers.md) that were used with older versions of Windows. - - - - - - - - diff --git a/windows-driver-docs-pr/battery/initializing-the-battery-class-device.md b/windows-driver-docs-pr/battery/initializing-the-battery-class-device.md index 6568ad2de3..3abc5a3e4e 100644 --- a/windows-driver-docs-pr/battery/initializing-the-battery-class-device.md +++ b/windows-driver-docs-pr/battery/initializing-the-battery-class-device.md @@ -11,39 +11,32 @@ ms.date: 04/20/2017 # Initializing the Battery Class Device - -## - - The [*AddDevice*](/windows-hardware/drivers/ddi/wdm/nc-wdm-driver_add_device) routine must initialize the battery class device and register the miniclass driver with the class driver. To do so, the miniclass driver calls the [**BatteryClassInitializeDevice**](/windows/win32/api/batclass/nf-batclass-batteryclassinitializedevice) routine. This call registers the miniclass driver with the class driver, so that the two drivers can use each other's support routines. This call also registers the battery device with the system so that it can be seen by the composite battery and the power meter. **BatteryClassInitializeDevice** requires a pointer to a [**BATTERY\_MINIPORT\_INFO**](/windows/win32/api/batclass/ns-batclass-battery_miniport_info) structure that contains the following information: -- In **MajorVersion** and **MinorVersion**, the major and minor version numbers of the class driver that this miniclass driver supports. +- In **MajorVersion** and **MinorVersion**, the major and minor version numbers of the class driver that this miniclass driver supports. The version numbers are defined in Batclass.h as BATTERY\_CLASS\_MAJOR\_VERSION and BATTERY\_CLASS\_MINOR\_VERSION, respectively. -- In **QueryTag**, the entry point of the miniclass driver's [*BatteryMiniQueryTag*](/windows/win32/api/batclass/nc-batclass-bclass_query_tag_callback) routine. +- In **QueryTag**, the entry point of the miniclass driver's [*BatteryMiniQueryTag*](/windows/win32/api/batclass/nc-batclass-bclass_query_tag_callback) routine. -- In **QueryInformation**, the entry point of the miniclass driver's [*BatteryMiniQueryInformation*](/windows/win32/api/batclass/nc-batclass-bclass_query_information_callback) routine. +- In **QueryInformation**, the entry point of the miniclass driver's [*BatteryMiniQueryInformation*](/windows/win32/api/batclass/nc-batclass-bclass_query_information_callback) routine. -- In **SetInformation**, the entry point of the miniclass driver's [*BatteryMiniSetInformation*](/windows/win32/api/batclass/nc-batclass-bclass_set_information_callback) routine. +- In **SetInformation**, the entry point of the miniclass driver's [*BatteryMiniSetInformation*](/windows/win32/api/batclass/nc-batclass-bclass_set_information_callback) routine. -- In **SetStatusNotify**, the entry point of the miniclass driver's [*BatteryMiniSetStatusNotify*](/windows/win32/api/batclass/nc-batclass-bclass_set_status_notify_callback) routine. +- In **SetStatusNotify**, the entry point of the miniclass driver's [*BatteryMiniSetStatusNotify*](/windows/win32/api/batclass/nc-batclass-bclass_set_status_notify_callback) routine. -- In **DisableStatusNotify**, the entry point of the miniclass driver's [*BatteryMiniDisableStatusNotify*](/windows/win32/api/batclass/nc-batclass-bclass_disable_status_notify_callback) routine. +- In **DisableStatusNotify**, the entry point of the miniclass driver's [*BatteryMiniDisableStatusNotify*](/windows/win32/api/batclass/nc-batclass-bclass_disable_status_notify_callback) routine. -- In **Context**, a pointer to the miniclass driver's context information. +- In **Context**, a pointer to the miniclass driver's context information. The context information is typically a pointer to the FDO device extension, which is passed back to the miniclass driver each time the class driver calls a [BatteryMini*Xxx*](/windows-hardware/drivers/ddi/_battery/) routine. -- In **Pdo**, a pointer to the PDO for the device. +- In **Pdo**, a pointer to the PDO for the device. -- In **DeviceName**, a NULL parameter; PnP devices should not have names. +- In **DeviceName**, a NULL parameter; PnP devices should not have names. After setting up this structure, the miniclass driver attaches itself to the battery class driver by calling **BatteryClassInitializeDevice**, and passing a pointer to the BATTERY\_MINIPORT\_INFO structure. In return, it receives a handle to be used in subsequent calls to battery class driver support routines. The miniclass driver should store the returned class handle in nonpaged memory. After calling **BatteryClassInitializeDevice**, the [*AddDevice*](/windows-hardware/drivers/ddi/wdm/nc-wdm-driver_add_device) routine might also need to initialize other device-specific data. - - - diff --git a/windows-driver-docs-pr/battery/installing-a-battery-driver.md b/windows-driver-docs-pr/battery/installing-a-battery-driver.md index ff0906f2a5..35d7b2ee9c 100644 --- a/windows-driver-docs-pr/battery/installing-a-battery-driver.md +++ b/windows-driver-docs-pr/battery/installing-a-battery-driver.md @@ -4,22 +4,18 @@ description: Installing a Battery Driver keywords: - battery miniclass drivers WDK , installing - battery class drivers WDK , installing -ms.date: 04/20/2017 +ms.date: 05/05/2023 --- # Installing a Battery Driver - -## - - -A battery driver's INF file specifies information about the driver and the devices it controls. All battery devices are members of the Battery class and the battery class installer installs the driver. +A battery driver's INF file specifies information about the driver and the devices it controls. All battery devices are members of the Battery class. This section describes battery-specific entries in the INF file. For more information about creating and distributing INF files and installing drivers, see [Creating an INF File](../install/overview-of-inf-files.md) and [INF File Sections and Directives](../install/index.md). A battery driver's INF file includes the sections described below. -### Version +## Version A battery driver's INF file specifies the Battery class and its GUID, using the [**INF Version section**](../install/inf-version-section.md), as shown in the following example: @@ -29,11 +25,13 @@ Signature="$WINDOWS NT$" Class=Battery ClassGuid={72631e54-78a4-11d0-bcf7-00aa00b7b32a} Provider=%MyCo% +CatalogFile=ExampleCatalog.cat +PnpLockdown=1 ``` Note that %MyCo% must be defined in an [**INF Strings section**](../install/inf-strings-section.md) (not shown). -### DestinationDirs +## DestinationDirs In the [**INF DestinationDirs section**](../install/inf-destinationdirs-section.md), a battery driver's INF specifies the Drivers directory (12) as the default for all files. @@ -42,26 +40,26 @@ In the [**INF DestinationDirs section**](../install/inf-destinationdirs-section. DefaultDestDir = 12 ``` -### Manufacturer +## Manufacturer The [**INF Manufacturer section**](../install/inf-manufacturer-section.md) defines the manufacturer of the device. ``` syntax [Manufacturer] -%MyCo%=MyCompany +%MyCo%=MyCompany,NTamd64 ``` -### *Models* +## *Models* The [**INF *Models* section**](../install/inf-models-section.md) specifies the PnP hardware ID of the battery (shown as *pnpid* in the example). If the device is enumerated through ACPI, this section must also specify the EISA-style ID (shown as *acpidevnum*). For information about creating these IDs, see the *Advanced Configuration and Power Interface Specification*, which is available through the [ACPI / Power Management](https://uefi.org/acpi/specs) website. ``` syntax -[MyCompany] +[MyCompany.NTamd64] %pnpid.DeviceDesc% = NewBatt_Inst,pnpid %ACPI\acpidevnum.DeviceDesc% = NewBatt_Inst,ACPI\acpidevnum ``` -### *DDInstall* +## *DDInstall* In the [**INF *DDInstall* section**](../install/inf-ddinstall-section.md) (named NewBatt\_Inst in the example), an [**INF CopyFiles directive**](../install/inf-copyfiles-directive.md) copies the battery class driver (*Battc.sys*) and the new miniclass driver (*NewBatt.sys*) to the destination specified in the **DestinationDirs** directive. @@ -71,14 +69,14 @@ CopyFiles = @NewBatt.sys CopyFiles = @battc.sys ``` -### *DDInstall*.Services +### *DDInstall*.Services The [**INF *DDInstall*.Services section**](../install/inf-ddinstall-services-section.md) includes an [**INF AddService directive**](../install/inf-addservice-directive.md) that specifies additional information about the battery driver. A battery driver's INF file should indicate that the driver is a kernel driver that uses normal error handling and starts during initialization of the operating system. Battery drivers specify the load order group Extended Base. ``` syntax [NewBatt_Inst.Services] AddService = NewBatt,2,NewBatt_Service_Inst ; function driver for the device - + [NewBatt_Service_Inst] DisplayName = %NewBatt.SvcDesc% ServiceType = 1 ; SERVICE_KERNEL_DRIVER @@ -86,4 +84,3 @@ StartType = 3 ; SERVICE_DEMAND_START ErrorControl = 1 ; SERVICE_ERROR_NORMAL% ServiceBinary = %12%\NewBatt.sys ``` - diff --git a/windows-driver-docs-pr/battery/installing-ups-minidrivers.md b/windows-driver-docs-pr/battery/installing-ups-minidrivers.md index b8545fe975..fb761efb4c 100644 --- a/windows-driver-docs-pr/battery/installing-ups-minidrivers.md +++ b/windows-driver-docs-pr/battery/installing-ups-minidrivers.md @@ -8,13 +8,6 @@ ms.date: 04/20/2017 # Installing UPS Minidrivers - -## - - UPS minidrivers are user-mode DLLs that can be installed using Microsoft Windows Installer (described in Windows SDK documentation) or an INF file (see [Creating an INF File](../install/overview-of-inf-files.md)). One responsibility of the installation operation is to create [UPS\\ServiceProviders registry entries](ups-serviceproviders-registry-entries.md). - - - diff --git a/windows-driver-docs-pr/battery/interaction-of-battery-class-and-miniclass-drivers.md b/windows-driver-docs-pr/battery/interaction-of-battery-class-and-miniclass-drivers.md index 87ff152f66..892227e52d 100644 --- a/windows-driver-docs-pr/battery/interaction-of-battery-class-and-miniclass-drivers.md +++ b/windows-driver-docs-pr/battery/interaction-of-battery-class-and-miniclass-drivers.md @@ -9,10 +9,6 @@ ms.date: 04/20/2017 # Interaction of Battery Class and Miniclass Drivers - -## - - Together, the battery class driver and the miniclass driver manage the computer's use of a battery. The following figure shows how these two drivers interact. ![diagram illustrating the interaction of battery class and miniclass drivers.](images/battmini.png) @@ -22,6 +18,3 @@ The miniclass driver is the primary function driver for the devices it controls. The class driver receives information and status from all the miniclass drivers and reports it to the power manager through the composite battery driver. In response to battery IOCTLs, the class driver calls [battery miniclass driver routines](/windows-hardware/drivers/ddi/_battery/) (BatteryMini*Xxx* routines) in the miniclass drivers to perform specific device control operations. Additionally, applications such as the power meter can send [**IRP\_MJ\_DEVICE\_CONTROL**](../kernel/irp-mj-device-control.md) requests to a miniclass driver to get information about a specific battery. The class driver is designed to handle the superset of possible battery information and conditions, including temperature, changes in capacity, and so forth; individual batteries vary in their ability to detect and report all these conditions. Each miniclass driver should be designed to manage its specific battery type and must respond appropriately to the class driver when asked for any information that the battery does not support. - - - diff --git a/windows-driver-docs-pr/battery/interaction-of-battery-status-and-notification-routines.md b/windows-driver-docs-pr/battery/interaction-of-battery-status-and-notification-routines.md index acc87161d0..19d1d412ef 100644 --- a/windows-driver-docs-pr/battery/interaction-of-battery-status-and-notification-routines.md +++ b/windows-driver-docs-pr/battery/interaction-of-battery-status-and-notification-routines.md @@ -11,10 +11,6 @@ ms.date: 04/20/2017 # Interaction of Battery Status and Notification Routines - -## - - The class driver can request and receive battery status -- and the miniclass driver can provide battery status -- in several ways. If the miniclass driver provides a [*BatteryMiniSetStatusNotify*](/windows/win32/api/batclass/nc-batclass-bclass_set_status_notify_callback) routine, the class driver can register to be notified when the battery's capacity exceeds or drops below a specified range, or when its power state changes. When any of the registered conditions occurs, the miniclass driver calls [**BatteryClassStatusNotify**](/windows/win32/api/batclass/nf-batclass-batteryclassstatusnotify). @@ -25,13 +21,10 @@ If the miniclass driver does not support *BatteryMiniSetStatusNotify*, the class Independent of any notification requests, a miniclass driver must call **BatteryClassStatusNotify** whenever any of the following occurs: -- The battery goes online or offline. +- The battery goes online or offline. -- The capacity of the battery becomes critically low. +- The capacity of the battery becomes critically low. -- The power state of the battery changes: it starts charging, starts discharging, stops charging, or stops discharging. +- The power state of the battery changes: it starts charging, starts discharging, stops charging, or stops discharging. Before reporting a critically low, discharging battery, the miniclass driver should attempt to solve the problem, as described previously in [Responding to Battery Status Queries](responding-to-battery-status-queries.md). - - - diff --git a/windows-driver-docs-pr/battery/overview-of-system-battery-management.md b/windows-driver-docs-pr/battery/overview-of-system-battery-management.md index fa821454b7..82e855f58a 100644 --- a/windows-driver-docs-pr/battery/overview-of-system-battery-management.md +++ b/windows-driver-docs-pr/battery/overview-of-system-battery-management.md @@ -16,23 +16,19 @@ ms.date: 04/20/2017 # Overview of System Battery Management - -## - - Battery management involves the following system components: -- The battery GUI, which presents status information to users and allows them to set battery options +- The battery GUI, which presents status information to users and allows them to set battery options -- The power manager +- The power manager -- The composite battery driver, a kernel-mode driver supplied by Microsoft +- The composite battery driver, a kernel-mode driver supplied by Microsoft -- The battery class driver, a kernel-mode driver supplied by Microsoft +- The battery class driver, a kernel-mode driver supplied by Microsoft -- Battery miniclass drivers for individual battery devices +- Battery miniclass drivers for individual battery devices -- Devices, including batteries and some Uninterruptible Power Supplies (UPS) +- Devices, including batteries and some Uninterruptible Power Supplies (UPS) ![diagram illustrating the components of battery management .](images/compbatt.png) @@ -40,26 +36,17 @@ Devices controlled by battery miniclass drivers include batteries and some UPS d **Note**   For UPS units connected to COM ports, [writing a UPS minidriver](writing-ups-minidrivers.md) is preferable to writing a battery miniclass driver for operating systems prior to Windows Vista. - - As shown in the preceding figure, the role of each component in battery operations is as follows: -- A bus driver and one or more optional filter drivers, such as an ACPI filter, might be layered between the device and its miniclass driver. - -- A *battery miniclass driver* is the function driver for a specific type of battery or UPS device. A system can have as many battery miniclass drivers as it has different types of batteries. - -- The *composite battery driver* keeps track of the status of all the batteries in the system and acts as an intermediary between the power manager and the battery class/miniclass drivers. The composite battery driver receives IRPs from the power manager and notifies the power manager when the battery status changes (for example, when system battery power becomes critically low). The composite battery driver interacts with the battery class driver in much the same way that a battery miniclass driver does, but it is transparent to other miniclass drivers. The system has one composite battery driver, supplied by Microsoft. - -- The *battery class driver* supports all the battery miniclass drivers and the composite battery driver. The system has one battery class driver, supplied by Microsoft. - -- The *power manager* sends power and Plug and Play (PnP) IRPs to battery device stacks through the composite battery driver. The power manager does not interact directly with the battery class or miniclass drivers; all IRPs are sent through the composite battery driver. - -- The *battery GUI* gets system battery status from the composite battery driver through the power manager and presents the information to the user. The GUI also sends IRPs to the battery miniclass drivers for device-specific information. The system has one battery GUI, supplied by the hardware vendor. +- A bus driver and one or more optional filter drivers, such as an ACPI filter, might be layered between the device and its miniclass driver. - +- A *battery miniclass driver* is the function driver for a specific type of battery or UPS device. A system can have as many battery miniclass drivers as it has different types of batteries. - +- The *composite battery driver* keeps track of the status of all the batteries in the system and acts as an intermediary between the power manager and the battery class/miniclass drivers. The composite battery driver receives IRPs from the power manager and notifies the power manager when the battery status changes (for example, when system battery power becomes critically low). The composite battery driver interacts with the battery class driver in much the same way that a battery miniclass driver does, but it is transparent to other miniclass drivers. The system has one composite battery driver, supplied by Microsoft. +- The *battery class driver* supports all the battery miniclass drivers and the composite battery driver. The system has one battery class driver, supplied by Microsoft. +- The *power manager* sends power and Plug and Play (PnP) IRPs to battery device stacks through the composite battery driver. The power manager does not interact directly with the battery class or miniclass drivers; all IRPs are sent through the composite battery driver. +- The *battery GUI* gets system battery status from the composite battery driver through the power manager and presents the information to the user. The GUI also sends IRPs to the battery miniclass drivers for device-specific information. The system has one battery GUI, supplied by the hardware vendor. diff --git a/windows-driver-docs-pr/battery/responding-to-battery-class-driver-queries.md b/windows-driver-docs-pr/battery/responding-to-battery-class-driver-queries.md index 244d6de04d..bfd42991e8 100644 --- a/windows-driver-docs-pr/battery/responding-to-battery-class-driver-queries.md +++ b/windows-driver-docs-pr/battery/responding-to-battery-class-driver-queries.md @@ -12,10 +12,6 @@ ms.date: 04/20/2017 # Responding to Battery Class Driver Queries - -## - - The miniclass driver must provide the following three [BatteryMini*Xxx*](/windows-hardware/drivers/ddi/_battery/) routines, which report battery status: [*BatteryMiniQueryTag*](/windows/win32/api/batclass/nc-batclass-bclass_query_tag_callback) @@ -25,6 +21,3 @@ The miniclass driver must provide the following three [BatteryMini*Xxx*](/window [*BatteryMiniQueryStatus*](/windows/win32/api/batclass/nc-batclass-bclass_query_status_callback) The [**BatteryClassIoctl**](/windows/win32/api/batclass/nf-batclass-batteryclassioctl) routine in the class driver calls these miniclass driver routines when it receives IOCTLs requesting information about the batteries. - - - diff --git a/windows-driver-docs-pr/battery/responding-to-battery-information-queries.md b/windows-driver-docs-pr/battery/responding-to-battery-information-queries.md index 4fc34d58a3..443499f0c4 100644 --- a/windows-driver-docs-pr/battery/responding-to-battery-information-queries.md +++ b/windows-driver-docs-pr/battery/responding-to-battery-information-queries.md @@ -8,10 +8,6 @@ ms.date: 04/20/2017 # Responding to Battery Information Queries - -## - - The battery class driver calls the [*BatteryMiniQueryInformation*](/windows/win32/api/batclass/nc-batclass-bclass_query_information_callback) routine to get a variety of information about the current battery. This routine is declared as follows: ```cpp @@ -34,23 +30,20 @@ The *Level* parameter specifies the kind of information requested. The miniclass A miniclass driver should be prepared to handle requests for the following: -- Battery capabilities, chemistry, capacity, low-capacity alert levels, and reserve charge +- Battery capabilities, chemistry, capacity, low-capacity alert levels, and reserve charge -- Temperature, in tenths of a degree Kelvin +- Temperature, in tenths of a degree Kelvin -- Estimated remaining run time, in seconds +- Estimated remaining run time, in seconds -- Device name +- Device name -- Manufacturer's battery model name +- Manufacturer's battery model name -- Date of manufacture +- Date of manufacture -- Unique ID +- Unique ID -- Serial number +- Serial number Some batteries are not capable of reporting all this information. A miniclass driver should return STATUS\_INVALID\_DEVICE\_REQUEST for any information that its device cannot supply. - - - diff --git a/windows-driver-docs-pr/battery/responding-to-battery-status-queries.md b/windows-driver-docs-pr/battery/responding-to-battery-status-queries.md index 19f970bcc6..fd3296122c 100644 --- a/windows-driver-docs-pr/battery/responding-to-battery-status-queries.md +++ b/windows-driver-docs-pr/battery/responding-to-battery-status-queries.md @@ -13,10 +13,6 @@ ms.date: 04/20/2017 # Responding to Battery Status Queries - -## - - The battery class driver calls the miniclass driver's [*BatteryMiniQueryStatus*](/windows/win32/api/batclass/nc-batclass-bclass_query_status_callback) routine to get the power state, capacity, voltage, and discharge rate of a battery. The following is the prototype for this routine: ```cpp @@ -33,19 +29,16 @@ The *Context* parameter is a pointer to the context area that is allocated by th In the buffered BATTERY\_STATUS structure, the miniclass driver reports the battery's voltage, capacity, and charge/discharge rate to the extent that the miniclass driver can determine them. The miniclass driver also reports one or more of the following constants that describe the battery's power condition: -- BATTERY\_CHARGING +- BATTERY\_CHARGING -- BATTERY\_DISCHARGING +- BATTERY\_DISCHARGING -- BATTERY\_POWER\_ON\_LINE +- BATTERY\_POWER\_ON\_LINE -- BATTERY\_CRITICAL +- BATTERY\_CRITICAL The miniclass driver should not report a critically low, discharging battery (BATTERY\_CRITICAL and BATTERY\_DISCHARGING) until it has ascertained that the condition is not merely a transitory fluctuation and has exhausted all other means of remedying the situation. Such remedies might include switching to AC power or to another battery, if the miniclass driver can do so. When the miniclass driver reports a critically low, discharging battery, the power manager assumes that battery failure is imminent. If the battery supplies system power or is a secondary (rechargeable) cell, the system carries out the DC power policy for a critical battery. The details of the power policy vary from system to system, depending on hardware capabilities, application settings, and user preferences. Typically, the system attempts to enter a sleeping state or powers off the computer. For more information, see [System Power Policy](../kernel/system-power-policy.md). The class driver's [**BatteryClassStatusNotify**](/windows/win32/api/batclass/nf-batclass-batteryclassstatusnotify) routine and the miniclass driver's [*BatteryMiniQueryStatus*](/windows/win32/api/batclass/nc-batclass-bclass_query_status_callback), [*BatteryMiniSetStatusNotify*](/windows/win32/api/batclass/nc-batclass-bclass_set_status_notify_callback), and [*BatteryMiniDisableStatusNotify*](/windows/win32/api/batclass/nc-batclass-bclass_disable_status_notify_callback) routines are used in sequence by the two drivers to provide timely status information. For details, see [Interaction of Battery Status and Notification Routines](interaction-of-battery-status-and-notification-routines.md). - - - diff --git a/windows-driver-docs-pr/battery/responding-to-battery-tag-queries.md b/windows-driver-docs-pr/battery/responding-to-battery-tag-queries.md index 6c6b958280..e8100aa2b0 100644 --- a/windows-driver-docs-pr/battery/responding-to-battery-tag-queries.md +++ b/windows-driver-docs-pr/battery/responding-to-battery-tag-queries.md @@ -8,10 +8,6 @@ ms.date: 04/20/2017 # Responding to Battery Tag Queries - -## - - The battery tag is a ULONG counter initialized and incremented by the miniclass driver. The battery class driver calls [*BatteryMiniQueryTag*](/windows/win32/api/batclass/nc-batclass-bclass_query_tag_callback) to request the current value of the tag. This miniclass driver routine is declared as follows: @@ -32,6 +28,3 @@ Each time a battery is inserted, the miniclass driver must increment the value o If no battery is present, or if the miniclass driver cannot determine whether a battery is present, the miniclass driver should return STATUS\_NO\_SUCH\_DEVICE and set the value of the tag to BATTERY\_TAG\_INVALID. The class driver uses the battery tag internally and in calls to the miniclass driver to identify a specific instance of a battery. The miniclass driver should check the value of the battery tag that is passed to each of its standard routines to ensure that it corresponds to the current battery. If the tag is incorrect, the miniclass driver should return STATUS\_NO\_SUCH\_DEVICE. - - - diff --git a/windows-driver-docs-pr/battery/sample-ups-minidriver.md b/windows-driver-docs-pr/battery/sample-ups-minidriver.md index b68e2cfea3..5e0742adcb 100644 --- a/windows-driver-docs-pr/battery/sample-ups-minidriver.md +++ b/windows-driver-docs-pr/battery/sample-ups-minidriver.md @@ -8,6 +8,4 @@ ms.date: 04/01/2019 # Sample UPS Minidriver -## - A sample UPS minidriver is provided in the \\src\\general\\ups subdirectory of versions of the Windows Driver Development Kit (DDK) prior to Windows Vista. The sample contains code and comments to assist you in developing a UPS minidriver DLL. diff --git a/windows-driver-docs-pr/battery/setting-and-canceling-battery-notification.md b/windows-driver-docs-pr/battery/setting-and-canceling-battery-notification.md index af099f4010..c7775bc991 100644 --- a/windows-driver-docs-pr/battery/setting-and-canceling-battery-notification.md +++ b/windows-driver-docs-pr/battery/setting-and-canceling-battery-notification.md @@ -13,10 +13,6 @@ ms.date: 04/20/2017 # Setting and Canceling Battery Notification - -## - - A miniclass driver provides a [*BatteryMiniSetStatusNotify*](/windows/win32/api/batclass/nc-batclass-bclass_set_status_notify_callback) routine so that the class driver can request notification of specific conditions. The routine is declared as follows: ```cpp @@ -48,6 +44,3 @@ NTSTATUS The *Context* parameter is a pointer to the context area allocated by the miniclass driver and passed to the class driver in the BATTERY\_MINIPORT\_INFO structure at device initialization. Miniclass drivers can omit functionality for both routines and return STATUS\_NOT\_SUPPORTED. However, a miniclass driver that provides a *BatteryMiniSetStatusNotify* routine must provide a corresponding *BatteryMiniDisableStatusNotify* routine, and vice versa. - - - diff --git a/windows-driver-docs-pr/battery/supplying-battery-device-notification.md b/windows-driver-docs-pr/battery/supplying-battery-device-notification.md index fa586656b0..285159c0ee 100644 --- a/windows-driver-docs-pr/battery/supplying-battery-device-notification.md +++ b/windows-driver-docs-pr/battery/supplying-battery-device-notification.md @@ -14,13 +14,6 @@ ms.date: 04/20/2017 # Supplying Battery Device Notification - -## - - The miniclass driver is responsible for monitoring the status of the batteries it supports and notifying the class driver when important changes occur. In addition to the [*BatteryMiniQueryStatus*](/windows/win32/api/batclass/nc-batclass-bclass_query_status_callback) routine, the miniclass driver also supplies the [*BatteryMiniSetStatusNotify*](/windows/win32/api/batclass/nc-batclass-bclass_set_status_notify_callback) and [*BatteryMiniDisableStatusNotify*](/windows/win32/api/batclass/nc-batclass-bclass_disable_status_notify_callback) routines. The class driver uses the *BatteryMiniSetStatusNotify* and *BatteryMiniDisableStatusNotify* routines to request and cancel notification of specific battery states. These routines interact with the class and miniclass driver status routines as described in the next section. For more information about these two miniclass routines, see [Setting and Canceling Battery Notification](setting-and-canceling-battery-notification.md). - - - diff --git a/windows-driver-docs-pr/battery/supplying-required-battery-miniclass-driver-functionality.md b/windows-driver-docs-pr/battery/supplying-required-battery-miniclass-driver-functionality.md index 84bc8c97b7..ec6c70b05c 100644 --- a/windows-driver-docs-pr/battery/supplying-required-battery-miniclass-driver-functionality.md +++ b/windows-driver-docs-pr/battery/supplying-required-battery-miniclass-driver-functionality.md @@ -10,10 +10,6 @@ ms.date: 04/20/2017 # Supplying Required Battery Miniclass Driver Functionality - -## - - In addition to the routines required to support [Plug and Play](../kernel/introduction-to-plug-and-play.md), a battery miniclass driver must have the following routines: [DriverEntry](driverentry-routine-of-a-battery-miniclass-driver.md) @@ -44,7 +40,6 @@ The [BatteryMini*Xxx*](/windows-hardware/drivers/ddi/_battery/) routines are sup Battery miniclass drivers must include the following header files: -- Batclass.h - -- Ntddk.h or Wdm.h +- Batclass.h +- Ntddk.h or Wdm.h diff --git a/windows-driver-docs-pr/battery/unload-routine-of-a-battery-miniclass-driver.md b/windows-driver-docs-pr/battery/unload-routine-of-a-battery-miniclass-driver.md index 6e6b6c25b0..a9b52a6466 100644 --- a/windows-driver-docs-pr/battery/unload-routine-of-a-battery-miniclass-driver.md +++ b/windows-driver-docs-pr/battery/unload-routine-of-a-battery-miniclass-driver.md @@ -11,10 +11,6 @@ ms.date: 04/20/2017 # Unload Routine of a Battery Miniclass Driver - -## - - The *Unload* routine for a battery miniclass driver ensures that all the driver's devices have been removed and frees any resources the miniclass driver has allocated. The *Unload* routine should first check to ensure that all its devices have been removed and, if not, do the following for each remaining device: @@ -32,6 +28,3 @@ The *Unload* routine should first check to ensure that all its devices have been After all the miniclass driver's devices are unloaded, the *Unload* routine should free any resources allocated by the miniclass driver. The miniclass driver's *Unload* routine can be called at any time after all the driver's devices have been removed. The PnP Manager calls the *Unload* routine in the context of a system thread at IRQL = PASSIVE\_LEVEL. - - - diff --git a/windows-driver-docs-pr/battery/ups-minidriver-functionality.md b/windows-driver-docs-pr/battery/ups-minidriver-functionality.md index 9da88e4994..aabfac3be7 100644 --- a/windows-driver-docs-pr/battery/ups-minidriver-functionality.md +++ b/windows-driver-docs-pr/battery/ups-minidriver-functionality.md @@ -8,29 +8,22 @@ ms.date: 04/20/2017 # UPS Minidriver Functionality - -## - - A UPS minidriver must export the following set of functions, which are called by the system-supplied UPS service: -- [**UPSInit**](/windows-hardware/drivers/ddi/upssvc/nf-upssvc-upsinit) +- [**UPSInit**](/windows-hardware/drivers/ddi/upssvc/nf-upssvc-upsinit) -- [**UPSGetState**](/windows-hardware/drivers/ddi/upssvc/nf-upssvc-upsgetstate) +- [**UPSGetState**](/windows-hardware/drivers/ddi/upssvc/nf-upssvc-upsgetstate) -- [**UPSWaitForStateChange**](/windows-hardware/drivers/ddi/upssvc/nf-upssvc-upswaitforstatechange) +- [**UPSWaitForStateChange**](/windows-hardware/drivers/ddi/upssvc/nf-upssvc-upswaitforstatechange) -- [**UPSCancelWait**](/windows-hardware/drivers/ddi/upssvc/nf-upssvc-upscancelwait) +- [**UPSCancelWait**](/windows-hardware/drivers/ddi/upssvc/nf-upssvc-upscancelwait) -- [**UPSTurnOff**](/windows-hardware/drivers/ddi/upssvc/nf-upssvc-upsturnoff) +- [**UPSTurnOff**](/windows-hardware/drivers/ddi/upssvc/nf-upssvc-upsturnoff) -- [**UPSStop**](/windows-hardware/drivers/ddi/upssvc/nf-upssvc-upsstop) +- [**UPSStop**](/windows-hardware/drivers/ddi/upssvc/nf-upssvc-upsstop) Additionally, the minidriver must export a [**DLLMain**](/windows/desktop/Dlls/dllmain) function, as described in Microsoft Windows SDK documentation. Besides exporting these functions, the minidriver must provide initial values for [UPS registry entries](ups-registry-entries.md) and then modify the values as necessary to reflect UPS state changes. Typically, a UPS minidriver communicates with a UPS unit through a COM port by calling the [**CreateFile**](/windows/win32/api/fileapi/nf-fileapi-createfilea), [**ReadFile**](/windows/win32/api/fileapi/nf-fileapi-readfile), and [**WriteFile**](/windows/win32/api/fileapi/nf-fileapi-writefile) functions (described in Windows SDK documentation). The minidriver is responsible for implementing whatever communication protocol the UPS unit supports. - - - diff --git a/windows-driver-docs-pr/battery/ups-registry-entries.md b/windows-driver-docs-pr/battery/ups-registry-entries.md index ace4b3d6d3..8e5e172ec2 100644 --- a/windows-driver-docs-pr/battery/ups-registry-entries.md +++ b/windows-driver-docs-pr/battery/ups-registry-entries.md @@ -10,10 +10,6 @@ ms.date: 04/20/2017 # UPS Registry Entries - -## - - UPS registry entries provide model-specific information about a system's UPS. A vendor-supplied UPS minidriver is responsible for supplying values for some of these registry entries, which are stored under the UPS service's tree. The following registry key is the root of the UPS service tree: @@ -22,24 +18,21 @@ The following registry key is the root of the UPS service tree: The UPS registry entries are organized under the following four keys: -- **UPS** -- Service control manager entries, and entries used by the Windows NT 4.0 UPS service +- **UPS** -- Service control manager entries, and entries used by the Windows NT 4.0 UPS service These entries are for system use only. Vendors must not modify these entries. -- **UPS**\\**Config** -- Information pertaining to the configuration of the UPS service. +- **UPS**\\**Config** -- Information pertaining to the configuration of the UPS service. These entries are for system use only. Vendors must not modify these entries. -- [UPS\\Status Registry Entries](ups-status-registry-entries.md) -- Status information. +- [UPS\\Status Registry Entries](ups-status-registry-entries.md) -- Status information. These entries are for vendor and system use. If vendors create and modify these entries as appropriate, **Power Options** displays them. -- [UPS\\ServiceProviders Registry Entries](ups-serviceproviders-registry-entries.md) -- Entries for different vendor and model UPS devices. +- [UPS\\ServiceProviders Registry Entries](ups-serviceproviders-registry-entries.md) -- Entries for different vendor and model UPS devices. These entries are for vendor and system use. Vendors should create these entries while [installing UPS minidrivers](installing-ups-minidrivers.md). The system's UPS service copies UPS model-specific values to other, system-controlled registry locations after an administrator has selected the UPS model for use. - - - diff --git a/windows-driver-docs-pr/battery/ups-serviceproviders-registry-entries.md b/windows-driver-docs-pr/battery/ups-serviceproviders-registry-entries.md index 3b33e5c3cd..3e9bf373b5 100644 --- a/windows-driver-docs-pr/battery/ups-serviceproviders-registry-entries.md +++ b/windows-driver-docs-pr/battery/ups-serviceproviders-registry-entries.md @@ -6,15 +6,11 @@ ms.date: 04/20/2017 # UPS\\ServiceProviders Registry Entries - -## - - Under the **UPS**\\**ServiceProviders** registry key, a UPS vendor should create a vendor-specific subkey. Under this subkey, the vendor should create an entry for each UPS model. Vendors must create these registry entries while [installing UPS minidrivers](installing-ups-minidrivers.md). Each model-specific entry consists of a value name and a value. The value name should be the name of the UPS model. The value associated with this name is a string consisting of two parts: -- The first part of the value string represents a hexadecimal bitmask identifying the model's capabilities. Bit values are defined in the following table. +- The first part of the value string represents a hexadecimal bitmask identifying the model's capabilities. Bit values are defined in the following table. @@ -65,7 +61,7 @@ Each model-specific entry consists of a value name and a value. The value name s -- The second part of the string is optional. It represents the path and name of the UPS minidriver. If this path and name is supplied, it must be preceded by a semicolon (;). If only the name is supplied, a default path of %SystemRoot%\\system32 is used. +- The second part of the string is optional. It represents the path and name of the UPS minidriver. If this path and name is supplied, it must be preceded by a semicolon (;). If only the name is supplied, a default path of %SystemRoot%\\system32 is used. After a UPS minidriver has been installed, and after a system administrator has enabled the UPS using **Power Options**, the system's UPS service copies model-specific **UPS**\\**ServiceProviders** values to other, system-controlled registry locations. @@ -77,9 +73,6 @@ UPS\ServiceProviders Back-UPS "0x7f" Smart-UPS "0x1;apcups.dll" ``` - - - diff --git a/windows-driver-docs-pr/battery/ups-status-registry-entries.md b/windows-driver-docs-pr/battery/ups-status-registry-entries.md index 90538579a7..a6435a31c1 100644 --- a/windows-driver-docs-pr/battery/ups-status-registry-entries.md +++ b/windows-driver-docs-pr/battery/ups-status-registry-entries.md @@ -6,10 +6,6 @@ ms.date: 04/20/2017 # UPS\\Status Registry Entries - -## - - The following registry entries, under the **UPS**\\**Status** key, must be set by UPS minidrivers. ### BatteryCapacity @@ -63,9 +59,6 @@ The current status of the UPS batteries. Values are listed in the following tabl
- - - Default Value 0 @@ -106,9 +99,6 @@ The status of the communication path to the UPS. Values are listed in the follow - - - Default Value 1 @@ -191,14 +181,8 @@ Reports the status of utility-supplied power into the UPS. Values are listed in - - - Default Value 0 - - - diff --git a/windows-driver-docs-pr/battery/writing-battery-miniclass-drivers.md b/windows-driver-docs-pr/battery/writing-battery-miniclass-drivers.md index 708da2055f..ef5a48d3d0 100644 --- a/windows-driver-docs-pr/battery/writing-battery-miniclass-drivers.md +++ b/windows-driver-docs-pr/battery/writing-battery-miniclass-drivers.md @@ -13,10 +13,6 @@ ms.date: 04/20/2017 # Writing Battery Miniclass Drivers - -## - - A battery typically has a pair of drivers: the generic battery class driver that Microsoft provides, and a miniclass driver written specifically for that individual type of battery. The class driver defines the overall functionality of the batteries in the system and interacts with the power manager. @@ -46,11 +42,3 @@ Information about writing battery miniclass drivers is organized as follows: [Unload Routine of a Battery Miniclass Driver](unload-routine-of-a-battery-miniclass-driver.md) [Installing a Battery Driver](installing-a-battery-driver.md) - - - - - - - - diff --git a/windows-driver-docs-pr/battery/writing-ups-minidrivers.md b/windows-driver-docs-pr/battery/writing-ups-minidrivers.md index 774ae7fca3..8f7d3702ea 100644 --- a/windows-driver-docs-pr/battery/writing-ups-minidrivers.md +++ b/windows-driver-docs-pr/battery/writing-ups-minidrivers.md @@ -14,21 +14,17 @@ ms.date: 04/20/2017 # Writing UPS Minidrivers - -## - - If an uninterruptible power supply (UPS) is connected to a Microsoft Windows system, the **UPS** tab for **Power Options** in Control Panel provides information about the UPS. On Windows Server 2003, Windows XP, and Windows 2000, a system-supplied UPS service provides support for UPS units that are connected to COM ports and that support "simple signaling," which provides very limited control capabilities and status information. On Windows Server 2003, Windows XP, and Windows 2000, if your UPS model is connected to a COM port and supports "smart signaling," you should provide a UPS minidriver. This minidriver, which is a user-mode DLL called by the system's UPS service, performs the following operations: -- Initializes the communication path to the UPS. +- Initializes the communication path to the UPS. -- Updates registry entries that **Power Options** uses to obtain model-specific information to display. +- Updates registry entries that **Power Options** uses to obtain model-specific information to display. -- Turns off the UPS power upon request. +- Turns off the UPS power upon request. -- Monitors the UPS unit for state changes. +- Monitors the UPS unit for state changes. For more information about UPS minidrivers, see the following topics: @@ -40,9 +36,4 @@ For more information about UPS minidrivers, see the following topics: [Installing UPS Minidrivers](installing-ups-minidrivers.md) -**Note**   Windows Vista and later versions of Windows do not support UPS units that are connected to COM ports. These Windows versions continue to support UPS units connected over [USB](../index.yml). - - - - - +**Note**   Windows Vista and later versions of Windows do not support UPS units that are connected to COM ports. These Windows versions continue to support UPS units connected over [USB](../index.yml). \ No newline at end of file diff --git a/windows-driver-docs-pr/biometric/creating-a-device-interface-for-a-wbdi-driver.md b/windows-driver-docs-pr/biometric/creating-a-device-interface-for-a-wbdi-driver.md index f0d9ca9495..700e6dbac8 100644 --- a/windows-driver-docs-pr/biometric/creating-a-device-interface-for-a-wbdi-driver.md +++ b/windows-driver-docs-pr/biometric/creating-a-device-interface-for-a-wbdi-driver.md @@ -4,7 +4,7 @@ description: Creating a Device Interface for a WBDI Driver keywords: - biometric drivers WDK , device interfaces - device interfaces WDK biometric -ms.date: 04/20/2017 +ms.date: 03/03/2023 --- # Creating a Device Interface for a WBDI Driver diff --git a/windows-driver-docs-pr/biometric/custom-control-codes.md b/windows-driver-docs-pr/biometric/custom-control-codes.md index 04fbd97dd3..8195bea71f 100644 --- a/windows-driver-docs-pr/biometric/custom-control-codes.md +++ b/windows-driver-docs-pr/biometric/custom-control-codes.md @@ -3,7 +3,7 @@ title: Custom Control Codes description: vendors can define custom control codes keywords: - biometric drivers WDK , control codes -ms.date: 11/13/2017 +ms.date: 03/03/2023 --- # Custom Control Codes diff --git a/windows-driver-docs-pr/biometric/getting-started-with-biometric-drivers.md b/windows-driver-docs-pr/biometric/getting-started-with-biometric-drivers.md index e5398213f4..df89dbd350 100644 --- a/windows-driver-docs-pr/biometric/getting-started-with-biometric-drivers.md +++ b/windows-driver-docs-pr/biometric/getting-started-with-biometric-drivers.md @@ -3,7 +3,7 @@ title: Getting Started with Biometric Drivers description: Getting Started with Biometric Drivers keywords: - biometric drivers WDK , about biometric drivers -ms.date: 04/20/2017 +ms.date: 03/03/2023 --- # Getting Started with Biometric Drivers diff --git a/windows-driver-docs-pr/biometric/hardware-considerations-for-biometric-drivers.md b/windows-driver-docs-pr/biometric/hardware-considerations-for-biometric-drivers.md index 4174688f4f..9a7adda1b5 100644 --- a/windows-driver-docs-pr/biometric/hardware-considerations-for-biometric-drivers.md +++ b/windows-driver-docs-pr/biometric/hardware-considerations-for-biometric-drivers.md @@ -3,7 +3,7 @@ title: Hardware Considerations for Biometric Drivers description: Hardware Considerations for Biometric Drivers keywords: - biometric drivers WDK , hardware considerations -ms.date: 04/20/2017 +ms.date: 03/03/2023 --- # Hardware Considerations for Biometric Drivers diff --git a/windows-driver-docs-pr/biometric/index.md b/windows-driver-docs-pr/biometric/index.md index 9072ac7d9f..257dba016f 100644 --- a/windows-driver-docs-pr/biometric/index.md +++ b/windows-driver-docs-pr/biometric/index.md @@ -2,7 +2,7 @@ title: Biometric Devices Design Guide description: Biometric Devices Design Guide ms.assetid: 78270890-4ea2-403e-bbd7-84a22581bbb7 -ms.date: 04/20/2017 +ms.date: 03/03/2023 ms.topic: article --- diff --git a/windows-driver-docs-pr/biometric/installing-a-biometric-driver.md b/windows-driver-docs-pr/biometric/installing-a-biometric-driver.md index 24d4d4c049..e5331b336e 100644 --- a/windows-driver-docs-pr/biometric/installing-a-biometric-driver.md +++ b/windows-driver-docs-pr/biometric/installing-a-biometric-driver.md @@ -4,36 +4,36 @@ description: Installing a Biometric Driver keywords: - biometric drivers WDK , installing - installing biometric drivers WDK biometric -ms.date: 04/20/2017 +ms.date: 05/05/2023 --- # Installing a Biometric Driver - Vendors can provide an INF file to install a WBDI driver. -The following is a list of guidelines for biometric device installation. The code examples in this topic are taken from the WudfBioUsbSample.inx file of the [WudfBioUsbSample](https://github.com/Microsoft/Windows-driver-samples/tree/master/biometrics/driver): +The following is a list of guidelines for biometric device installation. The code examples in this article are taken from the WudfBioUsbSample.inx file of the [WudfBioUsbSample](https://github.com/Microsoft/Windows-driver-samples/tree/main/biometrics/driver): -- WBDI drivers should specify a class of "Biometric." Set ClassGuid equal to the value that corresponds to GUID\_DEVCLASS\_BIOMETRIC in Devguid.h: +- WBDI drivers should specify a class of "Biometric." Set ClassGuid equal to the value that corresponds to GUID_DEVCLASS_BIOMETRIC in Devguid.h: - ```cpp + ```inf [Version] - Signature="$Windows NT$" + ... Class=Biometric ClassGuid={53D29EF7-377C-4D14-864B-EB3A85769359} + ... ``` -- In your .HW section, provide AddReg directives to specify three sections that contain entries to be added to the registry: +- In your .HW section, provide AddReg directives to specify three sections that contain entries to be added to the registry: - ```cpp + ```inf [Biometric_Install.NT.hw] AddReg=Biometric_Device_AddReg AddReg=DriverPlugInAddReg, DatabaseAddReg ``` -- Provide the named sections referred to in the .HW section. The \[Biometric\_Device\_AddReg\] section sets values for the biometric device, including the exclusive flag and system wake/device idle. To be recognized by Windows Biometric Framework, UMDF-based WBDI drivers must set the "Exclusive" value to 1. The first two lines of the \[Biometric\_Device\_AddReg\] section specify access control list (ACL) rights so that the device can only be opened by an administrator or the local system account. When you specify these ACL rights, third-party applications cannot open the device and capture fingerprint data when the WinBio service is not running. For example: +- Provide the named sections referred to in the .HW section. The \[Biometric_Device_AddReg\] section sets values for the biometric device, including the exclusive flag and system wake/device idle. To be recognized by Windows Biometric Framework, UMDF-based WBDI drivers must set the "Exclusive" value to 1. The first two lines of the \[Biometric_Device_AddReg\] section specify access control list (ACL) rights so that the device can only be opened by an administrator or the local system account. When you specify these ACL rights, third-party applications can't open the device and capture fingerprint data when the WinBio service isn't running. For example: - ```cpp + ```inf [Biometric_Device_AddReg] HKR,,"DeviceCharacteristics",0x10001,0x0100 ; Use same security checks on relative opens HKR,,"Security",,"D:P(A;;GA;;;BA)(A;;GA;;;SY)" ; Allow generic-all access to Built-in administrators and Local system @@ -46,13 +46,13 @@ The following is a list of guidelines for biometric device installation. The cod HKR,,"DefaultIdleTimeout",0x00010001,5000 ``` - A WBDI driver that exposes functionality to a legacy (non-WBDI) biometric stack should set the Exclusive value to zero. If this value is set to zero, the Windows Biometric Framework does not attempt to control the device and the device is not exposed through WBF. + A WBDI driver that exposes functionality to a legacy (non-WBDI) biometric stack should set the Exclusive value to zero. If this value is set to zero, the Windows Biometric Framework doesn't attempt to control the device, and the device isn't exposed through WBF. - Vendors can have a single driver binary that can work with legacy stacks and WBF, but the two cannot operate simultaneously. WBF will only operate if the device can be opened with exclusive access. + Vendors can have a single driver binary that can work with legacy stacks and WBF, but the two can't operate simultaneously. WBF will only operate if the device can be opened with exclusive access. -- The second named section contains registry values for the plug-in adapters. The sample uses the Microsoft-provided sensor adapter and storage adapter. This section also enables Windows log-in support by setting the SystemSensor value: +- The second named section contains registry values for the plug-in adapters. The sample uses the Microsoft-provided sensor adapter and storage adapter. This section also enables Windows log-in support by setting the SystemSensor value: - ```cpp + ```inf [DriverPlugInAddReg] HKR,WinBio\Configurations,DefaultConfiguration,,"0" HKR,WinBio\Configurations\0,SensorMode,0x10001,1 ; Basic - 1, Advanced - 2 @@ -63,9 +63,9 @@ The following is a list of guidelines for biometric device installation. The cod HKR,WinBio\Configurations\0,DatabaseId,,"6E9D4C5A-55B4-4c52-90B7-DDDC75CA4D50" ; Unique database GUID ``` -- Finally, the third section sets the following registry values for the database service. The identifying GUID must be unique for each vendor database of a certain format. For instance, in this code example from the sample, change 6E9D4C5A-55B4-4c52-90B7-DDDC75CA4D50 to your own unique GUID in your INF file. +- Finally, the third section sets the following registry values for the database service. The identifying GUID must be unique for each vendor database of a certain format. For instance, in this code example from the sample, change 6E9D4C5A-55B4-4c52-90B7-DDDC75CA4D50 to your own unique GUID in your INF file. - ```cpp + ```inf [DatabaseAddReg] HKLM,System\CurrentControlSet\Services\WbioSrvc\Databases\{6E9D4C5A-55B4-4c52-90B7-DDDC75CA4D50},BiometricType,0x00010001,0x00000008 HKLM,System\CurrentControlSet\Services\WbioSrvc\Databases\{6E9D4C5A-55B4-4c52-90B7-DDDC75CA4D50},Attributes,0x00010001,0x00000001 @@ -77,19 +77,16 @@ The following is a list of guidelines for biometric device installation. The cod HKLM,System\CurrentControlSet\Services\WbioSrvc\Databases\{6E9D4C5A-55B4-4c52-90B7-DDDC75CA4D50},ConnectionString,,"" ``` -- To differentiate WBDI and legacy drivers, vendors must set a Feature Score for the driver in the INX file. Feature Score is not set in the [WudfBioUsbSample](https://github.com/Microsoft/Windows-driver-samples/tree/master/biometrics/driver) sample. For more information about setting a Feature Score, see [Ranking a Biometric Driver on Windows Update](ranking-a-biometric-driver-on-windows-update.md). +- To differentiate WBDI and legacy drivers, vendors must set a Feature Score for the driver in the INX file. Feature Score isn't set in the [WudfBioUsbSample](https://github.com/Microsoft/Windows-driver-samples/tree/main/biometrics/driver) sample. For more information about setting a Feature Score, see [Ranking a Biometric Driver on Windows Update](ranking-a-biometric-driver-on-windows-update.md). For information about INX files and how they differ from INF files, see [Using INX Files to Create INF Files](../wdf/using-inx-files-to-create-inf-files.md). In order to replace a WBDI driver with a legacy driver, use the following procedure: -1. Close all currently active WBF applications. - -2. Uninstall the WBDI driver. - -3. Stop the WBF service, restart it, and then stop it again. +1. Close all currently active WBF applications. -4. Install the legacy driver. +1. Uninstall the WBDI driver. - +1. Stop the WBF service, restart it, and then stop it again. +1. Install the legacy driver. diff --git a/windows-driver-docs-pr/biometric/managing-queues-in-a-wbdi-driver.md b/windows-driver-docs-pr/biometric/managing-queues-in-a-wbdi-driver.md index bebb60b0f6..8735e896ec 100644 --- a/windows-driver-docs-pr/biometric/managing-queues-in-a-wbdi-driver.md +++ b/windows-driver-docs-pr/biometric/managing-queues-in-a-wbdi-driver.md @@ -4,7 +4,7 @@ description: Managing Queues in a WBDI Driver keywords: - biometric drivers WDK , managing queues - managing queues WDK biometric -ms.date: 04/20/2017 +ms.date: 03/03/2023 --- # Managing Queues in a WBDI Driver @@ -12,7 +12,7 @@ ms.date: 04/20/2017 WBDI drivers should create at least one queue to handle multiple concurrent requests from the service. If you are using UMDF, you can take advantage of its queue management support. -In [WudfBioUsbSample](https://github.com/Microsoft/Windows-driver-samples/tree/master/biometrics/driver), the CBiometricIoQueue class implements the I/O queue interface. +In [WudfBioUsbSample](https://github.com/Microsoft/Windows-driver-samples/tree/main/biometrics/driver), the CBiometricIoQueue class implements the I/O queue interface. In the method `CBiometricIoQueue::Initialize`, specifically, the driver queries the owning CBiometricIoQueue object for a pointer to the [IQueueCallbackDeviceIoControl](/windows-hardware/drivers/ddi/wudfddi/nn-wudfddi-iqueuecallbackdeviceiocontrol) interface that the framework uses to determine the event callback functions that the driver subscribes to on the queue: diff --git a/windows-driver-docs-pr/biometric/ranking-a-biometric-driver-on-windows-update.md b/windows-driver-docs-pr/biometric/ranking-a-biometric-driver-on-windows-update.md index 6b2ec33960..f9acadce96 100644 --- a/windows-driver-docs-pr/biometric/ranking-a-biometric-driver-on-windows-update.md +++ b/windows-driver-docs-pr/biometric/ranking-a-biometric-driver-on-windows-update.md @@ -4,7 +4,7 @@ description: Ranking a Biometric Driver on Windows Update keywords: - biometric drivers WDK , ranking on Windows Update - ranking biometric drivers WDK biometric -ms.date: 04/20/2017 +ms.date: 03/03/2023 --- # Ranking a Biometric Driver on Windows Update diff --git a/windows-driver-docs-pr/biometric/roadmap-for-developing-biometric-drivers.md b/windows-driver-docs-pr/biometric/roadmap-for-developing-biometric-drivers.md index 041f4b16a9..c6c1a00bbc 100644 --- a/windows-driver-docs-pr/biometric/roadmap-for-developing-biometric-drivers.md +++ b/windows-driver-docs-pr/biometric/roadmap-for-developing-biometric-drivers.md @@ -1,7 +1,7 @@ --- title: Roadmap for Developing Biometric Drivers description: Roadmap for Developing Biometric Drivers -ms.date: 04/20/2017 +ms.date: 03/03/2023 --- # Roadmap for Developing Biometric Drivers @@ -18,15 +18,15 @@ To create a biometric driver, follow these steps: - Step 3: Review the biometric driver sample in the WDK. - For Windows 7 and later operating systems, the driver code gallery includes a sample called [WudfBioUsbSample](https://github.com/Microsoft/Windows-driver-samples/tree/master/biometrics/driver). This sample WBDI driver is UMDF-based, and uses the [USB I/O Target](../wdf/usb-i-o-targets-in-umdf.md). + For Windows 7 and later operating systems, the driver code gallery includes a sample called [WudfBioUsbSample](https://github.com/Microsoft/Windows-driver-samples/tree/main/biometrics/driver). This sample WBDI driver is UMDF-based, and uses the [USB I/O Target](../wdf/usb-i-o-targets-in-umdf.md). - For more information about the WudfBioUsbSample sample, see the [sample description](https://github.com/Microsoft/Windows-driver-samples/tree/master/biometrics). + For more information about the WudfBioUsbSample sample, see the [sample description](https://github.com/Microsoft/Windows-driver-samples/tree/main/biometrics). - Step 4: Select a driver model for your biometric driver. Microsoft recommends that WBDI drivers are UMDF-based and use the USB I/O target. For information about UMDF, see [Introduction to UMDF](/previous-versions/ff554928(v=vs.85)). For information about the USB I/O target, see [Handling a USB I/O Target](../wdf/usb-i-o-targets-in-umdf.md). - [WudfBioUsbSample](https://github.com/Microsoft/Windows-driver-samples/tree/master/biometrics/driver) demonstrates how to implement a UMDF-based WBDI driver that uses a USB I/O target. + [WudfBioUsbSample](https://github.com/Microsoft/Windows-driver-samples/tree/main/biometrics/driver) demonstrates how to implement a UMDF-based WBDI driver that uses a USB I/O target. If you use UMDF, Microsoft recommends that you develop your biometric driver in C++. diff --git a/windows-driver-docs-pr/biometric/sample-biometric-driver.md b/windows-driver-docs-pr/biometric/sample-biometric-driver.md index f9afc86a05..cee7a4a606 100644 --- a/windows-driver-docs-pr/biometric/sample-biometric-driver.md +++ b/windows-driver-docs-pr/biometric/sample-biometric-driver.md @@ -3,15 +3,15 @@ title: Sample Biometric Driver description: Sample Biometric Driver keywords: - biometric drivers WDK , sample drivers -ms.date: 04/20/2017 +ms.date: 03/03/2023 --- # Sample Biometric Driver -As you read the biometric design guide, you should also review the [WudfBioUsbSample](https://github.com/Microsoft/Windows-driver-samples/tree/master/biometrics/driver) sample. WudfBioUsbSample is a UMDF-based WBDI driver that ships in Windows 7 Beta and later versions of the WDK. +As you read the biometric design guide, you should also review the [WudfBioUsbSample](https://github.com/Microsoft/Windows-driver-samples/tree/main/biometrics/driver) sample. WudfBioUsbSample is a UMDF-based WBDI driver that ships in Windows 7 Beta and later versions of the WDK. -WudfBioUsbSample is based on the [umdf\_fx2](https://github.com/Microsoft/Windows-driver-samples/tree/3528ffbb369fa0611aefd14c97bdd6ac5ee50c41/usb/umdf_fx2) sample driver. For information specific to WudfBioUsbSample, see the [WudfBioUsbSample description](https://github.com/Microsoft/Windows-driver-samples/tree/master/biometrics). +WudfBioUsbSample is based on the [umdf\_fx2](https://github.com/Microsoft/Windows-driver-samples/tree/3528ffbb369fa0611aefd14c97bdd6ac5ee50c41/usb/umdf_fx2) sample driver. For information specific to WudfBioUsbSample, see the [WudfBioUsbSample description](https://github.com/Microsoft/Windows-driver-samples/tree/main/biometrics). This documentation refers to WudfBioUsbSample to show some of the requirements of a WBDI driver. diff --git a/windows-driver-docs-pr/biometric/signing-wbdi-drivers.md b/windows-driver-docs-pr/biometric/signing-wbdi-drivers.md index 8d98756979..24b68e23de 100644 --- a/windows-driver-docs-pr/biometric/signing-wbdi-drivers.md +++ b/windows-driver-docs-pr/biometric/signing-wbdi-drivers.md @@ -1,7 +1,7 @@ --- title: Signing WBDI Drivers description: Signing WBDI Drivers -ms.date: 04/20/2017 +ms.date: 03/03/2023 --- # Signing WBDI Drivers diff --git a/windows-driver-docs-pr/biometric/supporting-biometric-ioctl-calling-sequence.md b/windows-driver-docs-pr/biometric/supporting-biometric-ioctl-calling-sequence.md index f51c9d087a..6d5d91118f 100644 --- a/windows-driver-docs-pr/biometric/supporting-biometric-ioctl-calling-sequence.md +++ b/windows-driver-docs-pr/biometric/supporting-biometric-ioctl-calling-sequence.md @@ -5,14 +5,14 @@ keywords: - biometric drivers WDK , supporting IOCTLs - supporting IOCTLs WDK biometric - IOCTLs WDK biometric -ms.date: 04/20/2017 +ms.date: 03/03/2023 --- # Supporting Biometric IOCTL Calling Sequence WBDI is a Windows standard IOCTL-based interface. When you write a WBDI driver, you must support a set of mandatory IOCTLs. You may additionally choose to support optional IOCTLs. You can find a complete list of mandatory and optional IOCTLs in [Biometric IOCTLs](/windows-hardware/drivers/ddi/_biometric/#ioctls). -A vendor-supplied WBDI driver should be prepared to receive IOCTL requests in the following order from the Windows Biometric Service (WBS). You can review examples of handlers for these IOCTLs in Device.cpp in [WudfBioUsbSample](https://github.com/Microsoft/Windows-driver-samples/tree/master/biometrics/driver). +A vendor-supplied WBDI driver should be prepared to receive IOCTL requests in the following order from the Windows Biometric Service (WBS). You can review examples of handlers for these IOCTLs in Device.cpp in [WudfBioUsbSample](https://github.com/Microsoft/Windows-driver-samples/tree/main/biometrics/driver). 1. The Windows Biometric Service or the sensor adapter initializes the biometric device and verifies that it is ready for use. The service or adapter sends an [**IOCTL\_BIOMETRIC\_GET\_ATTRIBUTES**](/windows-hardware/drivers/ddi/winbio_ioctl/ni-winbio_ioctl-ioctl_biometric_get_attributes) request. diff --git a/windows-driver-docs-pr/biometric/supporting-secure-channels-in-wbdi-drivers.md b/windows-driver-docs-pr/biometric/supporting-secure-channels-in-wbdi-drivers.md index 597c0d5b44..7ac4137a9c 100644 --- a/windows-driver-docs-pr/biometric/supporting-secure-channels-in-wbdi-drivers.md +++ b/windows-driver-docs-pr/biometric/supporting-secure-channels-in-wbdi-drivers.md @@ -4,7 +4,7 @@ description: Supporting Secure Channels in WBDI Drivers keywords: - biometric drivers WDK , secure channels - secure channels WDK biometric -ms.date: 04/20/2017 +ms.date: 03/03/2023 --- # Supporting Secure Channels in WBDI Drivers diff --git a/windows-driver-docs-pr/biometric/testing-biometric-drivers.md b/windows-driver-docs-pr/biometric/testing-biometric-drivers.md index 494d100bb3..c111b913d0 100644 --- a/windows-driver-docs-pr/biometric/testing-biometric-drivers.md +++ b/windows-driver-docs-pr/biometric/testing-biometric-drivers.md @@ -4,7 +4,7 @@ description: Testing Biometric Drivers keywords: - biometric drivers WDK , testing - testing biometric drivers WDK biometric -ms.date: 04/20/2017 +ms.date: 03/03/2023 --- # Testing Biometric Drivers diff --git a/windows-driver-docs-pr/biometric/using-wbdi-with-non-pnp-devices-or-proprietary-stacks.md b/windows-driver-docs-pr/biometric/using-wbdi-with-non-pnp-devices-or-proprietary-stacks.md index 411894f083..4ab69d3bcd 100644 --- a/windows-driver-docs-pr/biometric/using-wbdi-with-non-pnp-devices-or-proprietary-stacks.md +++ b/windows-driver-docs-pr/biometric/using-wbdi-with-non-pnp-devices-or-proprietary-stacks.md @@ -8,7 +8,7 @@ keywords: - legacy driver stacks WDK biometric - non-PnP devices WDK biometric - proprietary stacks WDK biometric -ms.date: 04/20/2017 +ms.date: 03/03/2023 --- # Using WBDI with Non-PnP Devices or Proprietary Stacks diff --git a/windows-driver-docs-pr/biometric/using-winusb-in-a-wbdi-driver.md b/windows-driver-docs-pr/biometric/using-winusb-in-a-wbdi-driver.md index 1211a44158..b5b2066271 100644 --- a/windows-driver-docs-pr/biometric/using-winusb-in-a-wbdi-driver.md +++ b/windows-driver-docs-pr/biometric/using-winusb-in-a-wbdi-driver.md @@ -3,7 +3,7 @@ title: Using WinUSB in a WBDI Driver description: Using WinUSB in a WBDI Driver keywords: - biometric drivers WDK , WinUSB -ms.date: 04/20/2017 +ms.date: 03/03/2023 --- # Using WinUSB in a WBDI Driver @@ -15,7 +15,7 @@ Microsoft recommends that WBDI drivers use the [USB I/O target](../wdf/usb-i-o-t An INF file that installs a UMDF driver must contain a WDF-specific **DDInstall** section. If you use the USB I/O target in UMDF, you must set the UmdfDispatcher registry directive within this **DDInstall** section. -The following section from WudfBioUsbSample.inx in the [WudfBioUsbSample](https://github.com/Microsoft/Windows-driver-samples/tree/master/biometrics/driver) sample shows how to set this directive: +The following section from WudfBioUsbSample.inx in the [WudfBioUsbSample](https://github.com/Microsoft/Windows-driver-samples/tree/main/biometrics/driver) sample shows how to set this directive: ```cpp [Biometric_Install.NT.Wdf] @@ -31,7 +31,7 @@ For specific information about UmdfDispatcher, see [Specifying the UmdfDispatche WinUsb can handle multiple outstanding read requests. Devices that require minimal latency between read operations during a scan should keep some number of outstanding asynchronous read requests pending. If the driver makes asynchronous requests, WinUsb issues these requests before the transfer back to user mode for the completion routines of earlier read requests. -You can refer to the `CBiometricDevice::InitiatePendingRead` method in Device.cpp in [WudfBioUsbSample](https://github.com/Microsoft/Windows-driver-samples/tree/master/biometrics/driver) to see a code example of how to pend a read request. +You can refer to the `CBiometricDevice::InitiatePendingRead` method in Device.cpp in [WudfBioUsbSample](https://github.com/Microsoft/Windows-driver-samples/tree/main/biometrics/driver) to see a code example of how to pend a read request. The code to pend a read request should be a loop of the following steps: diff --git a/windows-driver-docs-pr/biometric/windows-hello-driver-signing.md b/windows-driver-docs-pr/biometric/windows-hello-driver-signing.md index 2db6296720..98975a590b 100644 --- a/windows-driver-docs-pr/biometric/windows-hello-driver-signing.md +++ b/windows-driver-docs-pr/biometric/windows-hello-driver-signing.md @@ -4,7 +4,7 @@ description: Windows Hello fingerprint driver signature process keywords: - biometric drivers WDK , windows hello - signing biometric drivers -ms.date: 07/19/2017 +ms.date: 03/03/2023 --- diff --git a/windows-driver-docs-pr/bluetooth/accepting-l2cap-connections-in-a-bluetooth-profile-driver.md b/windows-driver-docs-pr/bluetooth/accepting-l2cap-connections-in-a-bluetooth-profile-driver.md index 509f6d9d5f..d46760e3b5 100644 --- a/windows-driver-docs-pr/bluetooth/accepting-l2cap-connections-in-a-bluetooth-profile-driver.md +++ b/windows-driver-docs-pr/bluetooth/accepting-l2cap-connections-in-a-bluetooth-profile-driver.md @@ -1,6 +1,6 @@ --- -title: Accepting L2CAP Connections in a Bluetooth Profile Driver -description: Accepting L2CAP Connections in a Bluetooth Profile Driver +title: Accepting L2CAP connections in a Bluetooth profile driver +description: Accepting L2CAP connections in a Bluetooth profile driver keywords: - L2CAP profile drivers WDK Bluetooth - Logical Link Controller and Adaptation Protocol WDK Bluetooth @@ -8,44 +8,37 @@ keywords: - connections WDK Bluetooth - remote connection notifications WDK Bluetooth - notifications WDK Bluetooth -ms.date: 04/20/2017 +ms.date: 10/07/2022 --- -# Accepting L2CAP Connections in a Bluetooth Profile Driver - +# Accepting L2CAP connections in a Bluetooth profile driver An L2CAP server profile driver responds to incoming Logical Link Control and Adaptation Protocol (L2CAP) connection requests from remote devices. For example, an L2CAP server profile driver for a PDA would respond to an incoming connection request from the PDA. -**To Receive Incoming L2CAP Connection Requests** +## To receive incoming L2CAP connection requests -1. **To receive incoming L2CAP connection requests from*any*remote device for a particular PSM**, profile drivers should first [build and send](building-and-sending-a-brb.md) a [**BRB\_L2CA\_REGISTER\_SERVER**](/previous-versions/ff536618(v=vs.85)) request, specifying **NULL** in the **BtAddress** member and 0 in the **Psm** member of the request's \_BRB\_L2CA\_REGISTER\_SERVER structure. Profile drivers must also register an [*L2CAP Callback Function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnbthport_indication_callback) with the Bluetooth driver stack when sending the **BRB\_L2CA\_REGISTER\_SERVER** request. This enables the Bluetooth driver stack to notify the profile driver of incoming L2CAP connection requests. +1. **To receive incoming L2CAP connection requests from*any*remote device for a particular PSM**, profile drivers should first [build and send](building-and-sending-a-brb.md) a [**BRB\_L2CA\_REGISTER\_SERVER**](/previous-versions/ff536618(v=vs.85)) request, specifying **NULL** in the **BtAddress** member and 0 in the **Psm** member of the request's \_BRB\_L2CA\_REGISTER\_SERVER structure. Profile drivers must also register an [*L2CAP Callback Function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnbthport_indication_callback) with the Bluetooth driver stack when sending the **BRB\_L2CA\_REGISTER\_SERVER** request. This enables the Bluetooth driver stack to notify the profile driver of incoming L2CAP connection requests. Then, profile drivers should [build and send](building-and-sending-a-brb.md) a [**BRB\_REGISTER\_PSM**](/previous-versions/ff536621(v=vs.85)) request so the Bluetooth driver stack will accept connections from the PSM registered by the request. Otherwise, the Bluetooth driver stack rejects all connection requests that have unknown (unregistered) connection requests. For more information about PSMs, see the [**\_BRB\_PSM**](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_brb_psm) structure. -2. **To receive incoming L2CAP connection requests from a*specific*remote device/PSM pair**, profile drivers should [build and send](building-and-sending-a-brb.md) a [**BRB\_L2CA\_REGISTER\_SERVER**](/previous-versions/ff536618(v=vs.85)) request, specifying the remote device's address in the **BtAddress** member, and PSM in the **Psm** member, of the request's accompanying \_BRB\_L2CA\_REGISTER\_SERVER structure. Profile drivers must also register an [*L2CAP Callback Function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnbthport_indication_callback) with the Bluetooth driver stack when sending the **BRB\_L2CA\_REGISTER\_SERVER** request. This enables the Bluetooth driver stack to notify the profile driver of incoming L2CAP connection requests. - -3. The profile driver should issue an [**IOCTL\_BTH\_SDP\_SUBMIT\_RECORD**](/windows-hardware/drivers/ddi/bthioctl/ni-bthioctl-ioctl_bth_sdp_submit_record). The profile driver can then register an SDP record that describes the service that the profile driver supports, so that remote systems can discover the new service by using SDP. - -4. When the Bluetooth driver stack receives an incoming L2CAP connection request from a remote device, the Bluetooth driver stack calls the [*L2CAP Callback Function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnbthport_indication_callback) registered earlier by the profile driver. The Bluetooth driver stack passes the value **IndicationRemoteConnect** to the *Indication* parameter of the callback function. +1. **To receive incoming L2CAP connection requests from a*specific*remote device/PSM pair**, profile drivers should [build and send](building-and-sending-a-brb.md) a [**BRB\_L2CA\_REGISTER\_SERVER**](/previous-versions/ff536618(v=vs.85)) request, specifying the remote device's address in the **BtAddress** member, and PSM in the **Psm** member, of the request's accompanying \_BRB\_L2CA\_REGISTER\_SERVER structure. Profile drivers must also register an [*L2CAP Callback Function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnbthport_indication_callback) with the Bluetooth driver stack when sending the **BRB\_L2CA\_REGISTER\_SERVER** request. This enables the Bluetooth driver stack to notify the profile driver of incoming L2CAP connection requests. -5. To respond to incoming connection requests, profile drivers should [build and send](building-and-sending-a-brb.md) a [**BRB\_L2CA\_OPEN\_CHANNEL\_RESPONSE**](/previous-versions/ff536616(v=vs.85)) request. The server profile driver uses the value passed from the Bluetooth driver stack in the *Parameters* parameter of the callback function to negotiate the connection settings with the remote device. Based on the value of the **Response** member of the [**\_BRB\_L2CA\_OPEN\_CHANNEL**](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_brb_l2ca_open_channel) structure passed with this request, the server profile driver accepts or rejects the connection request. +1. The profile driver should issue an [**IOCTL\_BTH\_SDP\_SUBMIT\_RECORD**](/windows-hardware/drivers/ddi/bthioctl/ni-bthioctl-ioctl_bth_sdp_submit_record). The profile driver can then register an SDP record that describes the service that the profile driver supports, so that remote systems can discover the new service by using SDP. -6. If the server profile driver accepts the connection, the Bluetooth driver stack can then call the [*L2CAP Callback Function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnbthport_indication_callback) as specified in the **Callback** member of the [**\_BRB\_L2CA\_OPEN\_CHANNEL**](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_brb_l2ca_open_channel) structure. The Bluetooth driver stack uses this function to notify the server profile driver of any changes to the L2CAP connection. +1. When the Bluetooth driver stack receives an incoming L2CAP connection request from a remote device, the Bluetooth driver stack calls the [*L2CAP Callback Function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnbthport_indication_callback) registered earlier by the profile driver. The Bluetooth driver stack passes the value **IndicationRemoteConnect** to the *Indication* parameter of the callback function. -**Note**   -- A single profile driver can register to receive incoming L2CAP connection requests from multiple, different remote device/PSM pairs by building and sending multiple **BRB\_L2CA\_REGISTER\_SERVER** requests to register multiple L2CAP servers, specifying unique remote device address and PSM pairs in the **BtAddress** and **Psm** members of the requests. +1. To respond to incoming connection requests, profile drivers should [build and send](building-and-sending-a-brb.md) a [**BRB\_L2CA\_OPEN\_CHANNEL\_RESPONSE**](/previous-versions/ff536616(v=vs.85)) request. The server profile driver uses the value passed from the Bluetooth driver stack in the *Parameters* parameter of the callback function to negotiate the connection settings with the remote device. Based on the value of the **Response** member of the [**\_BRB\_L2CA\_OPEN\_CHANNEL**](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_brb_l2ca_open_channel) structure passed with this request, the server profile driver accepts or rejects the connection request. -- A single profile driver can register to receive incoming L2CAP connection requests from *any* remote device for a particular PSM, as well as receive incoming L2CAP connection requests from multiple, different remote device/PSM pairs, by first registering to receive incoming L2CAP connection requests from any remote device for a particular PSM, and then registering to receive incoming L2CAP connection requests from a specific remote device/PSM pair as long as the particular PSM registered in the first step is not registered again. +1. If the server profile driver accepts the connection, the Bluetooth driver stack can then call the [*L2CAP Callback Function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnbthport_indication_callback) as specified in the **Callback** member of the [**\_BRB\_L2CA\_OPEN\_CHANNEL**](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_brb_l2ca_open_channel) structure. The Bluetooth driver stack uses this function to notify the server profile driver of any changes to the L2CAP connection. -- Multiple profile drivers cannot register to receive incoming L2CAP connection requests from any remote device for the same PSM. The Bluetooth driver stack only permits one profile driver to receive incoming L2CAP connection requests from any remote device for a particular PSM. - - +> [!NOTE] +> +> - A single profile driver can register to receive incoming L2CAP connection requests from multiple, different remote device/PSM pairs by building and sending multiple **BRB\_L2CA\_REGISTER\_SERVER** requests to register multiple L2CAP servers, specifying unique remote device address and PSM pairs in the **BtAddress** and **Psm** members of the requests. +> - A single profile driver can register to receive incoming L2CAP connection requests from *any* remote device for a particular PSM, as well as receive incoming L2CAP connection requests from multiple, different remote device/PSM pairs, by first registering to receive incoming L2CAP connection requests from any remote device for a particular PSM, and then registering to receive incoming L2CAP connection requests from a specific remote device/PSM pair as long as the particular PSM registered in the first step is not registered again. +> - Multiple profile drivers cannot register to receive incoming L2CAP connection requests from any remote device for the same PSM. The Bluetooth driver stack only permits one profile driver to receive incoming L2CAP connection requests from any remote device for a particular PSM. After the profile driver accepts a connection request, it can use other BRBs to send and receive data over the newly established L2CAP connection. To stop receiving notifications of remote device L2CAP connection attempts, profile drivers should [build and send](building-and-sending-a-brb.md) a [**BRB\_L2CA\_UNREGISTER\_SERVER**](/previous-versions/ff536619(v=vs.85)) request to unregister a server when the profile driver processes [**IRP\_MN\_REMOVE\_DEVICE**](../kernel/irp-mn-remove-device.md) Plug and Play remove notifications. For more information about notifications and callback functions, see [Supporting Bluetooth Event Notifications](supporting-bluetooth-event-notifications.md). - - - diff --git a/windows-driver-docs-pr/bluetooth/accepting-sco-connections-in-a-bluetooth-profile-driver.md b/windows-driver-docs-pr/bluetooth/accepting-sco-connections-in-a-bluetooth-profile-driver.md index bd60d294f0..789b6ab808 100644 --- a/windows-driver-docs-pr/bluetooth/accepting-sco-connections-in-a-bluetooth-profile-driver.md +++ b/windows-driver-docs-pr/bluetooth/accepting-sco-connections-in-a-bluetooth-profile-driver.md @@ -1,36 +1,32 @@ --- -title: Accepting SCO Connections in a Bluetooth Profile Driver -description: Accepting SCO Connections in a Bluetooth Profile Driver +title: Accepting SCO connections in a Bluetooth profile driver +description: Accepting SCO connections in a Bluetooth profile driver keywords: - Synchronous Connection-Oriented WDK Bluetooth - SCO profile drivers WDK Bluetooth - incoming SCO connection requests WDK Bluetooth - remote connection notifications WDK Bluetooth -ms.date: 04/20/2017 +ms.date: 10/07/2022 --- -# Accepting SCO Connections in a Bluetooth Profile Driver - +# Accepting SCO connections in a Bluetooth profile driver A SCO profile driver can register itself to respond to incoming Synchronous Connection-Oriented (SCO) connection requests from remote devices. For example, a SCO profile driver for a cordless telephony profile (CTP) device responds to an incoming SCO connection request from the CTP device, either accepting or rejecting the request. If the server profile driver accepts the request, the server profile driver responds to input from the device and passes that input to the Bluetooth driver stack. Server profile drivers must perform the following steps to accept incoming SCO connection requests from remote Bluetooth devices. -**To Receive Incoming SCO Connection Requests from Remote Devices** +## To receive incoming SCO connection requests from remote devices -1. Profile drivers should [build and send](building-and-sending-a-brb.md) a [**BRB\_SCO\_REGISTER\_SERVER**](/previous-versions/ff536628(v=vs.85)) request to register a [*SCO Callback Function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnsco_indication_callback) with the Bluetooth driver stack so the stack can notify the profile driver of incoming SCO connection requests. +1. Profile drivers should [build and send](building-and-sending-a-brb.md) a [**BRB\_SCO\_REGISTER\_SERVER**](/previous-versions/ff536628(v=vs.85)) request to register a [*SCO Callback Function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnsco_indication_callback) with the Bluetooth driver stack so the stack can notify the profile driver of incoming SCO connection requests. -2. When the Bluetooth driver stack receives an incoming SCO connection request from a remote device, it calls the [*SCO Callback Function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnsco_indication_callback) registered earlier by the profile driver. The Bluetooth driver stack passes the value **ScoIndicationRemoteConnect** to the *Indication* parameter of the callback function. +1. When the Bluetooth driver stack receives an incoming SCO connection request from a remote device, it calls the [*SCO Callback Function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnsco_indication_callback) registered earlier by the profile driver. The Bluetooth driver stack passes the value **ScoIndicationRemoteConnect** to the *Indication* parameter of the callback function. -3. To respond to incoming connection requests, profile drivers should build and send a [**BRB\_SCO\_OPEN\_CHANNEL\_RESPONSE**](/previous-versions/ff536627(v=vs.85)) request. Based on the value of the **Response** member of the [**\_BRB\_SCO\_OPEN\_CHANNEL**](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_brb_sco_open_channel) structure passed with this request, the server profile driver accepts or rejects the connection request. +1. To respond to incoming connection requests, profile drivers should build and send a [**BRB\_SCO\_OPEN\_CHANNEL\_RESPONSE**](/previous-versions/ff536627(v=vs.85)) request. Based on the value of the **Response** member of the [**\_BRB\_SCO\_OPEN\_CHANNEL**](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_brb_sco_open_channel) structure passed with this request, the server profile driver accepts or rejects the connection request. -4. If the server profile driver accepts the connection, the Bluetooth driver stack can then call the [*SCO Callback Function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnsco_indication_callback) as specified in the **Callback** member of the [**\_BRB\_SCO\_OPEN\_CHANNEL**](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_brb_sco_open_channel) structure to notify the server profile driver of any changes to the SCO connection. +1. If the server profile driver accepts the connection, the Bluetooth driver stack can then call the [*SCO Callback Function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnsco_indication_callback) as specified in the **Callback** member of the [**\_BRB\_SCO\_OPEN\_CHANNEL**](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_brb_sco_open_channel) structure to notify the server profile driver of any changes to the SCO connection. After the profile driver accepts a connection request, it can use other BRBs to send and receive data over the newly established SCO connection. To stop receiving notifications of remote device SCO connection attempts, profile drivers should [build and send](building-and-sending-a-brb.md) a [**BRB\_SCO\_UNREGISTER\_SERVER**](/previous-versions/ff536630(v=vs.85)) request to unregister a server when the profile driver processes [**IRP\_MN\_REMOVE\_DEVICE**](../kernel/irp-mn-remove-device.md) Plug and Play remove notifications. For more information about notifications and callback functions, see [Supporting Bluetooth Event Notifications](supporting-bluetooth-event-notifications.md). - - - diff --git a/windows-driver-docs-pr/bluetooth/accessing-sdp-service-information.md b/windows-driver-docs-pr/bluetooth/accessing-sdp-service-information.md index c827bd9418..0930f0480f 100644 --- a/windows-driver-docs-pr/bluetooth/accessing-sdp-service-information.md +++ b/windows-driver-docs-pr/bluetooth/accessing-sdp-service-information.md @@ -1,6 +1,6 @@ --- -title: Accessing SDP Service Information -description: Accessing SDP Service Information +title: Accessing SDP service information +description: Accessing SDP service information keywords: - Bluetooth WDK , SDP server communication - SDP WDK Bluetooth @@ -11,33 +11,28 @@ keywords: - IOCTL_BTH_SDP_CONNECT - searching SDP records WDK Bluetooth - IOCTL_BTH_SDP_SERVICE_SEARCH -ms.date: 04/20/2017 +ms.date: 10/07/2022 --- -# Accessing SDP Service Information - +# Accessing SDP service information After a profile driver submits a Service Discovery Protocol (SDP) record to advertise its services with SDP, other devices can discover these services by either searching specifically for the record or by browsing to find it. -To search for SDP records, a client profile driver must first use [**IOCTL\_BTH\_SDP\_CONNECT**](/windows-hardware/drivers/ddi/bthioctl/ni-bthioctl-ioctl_bth_sdp_connect) to connect to the SDP service of the remote device. +To search for SDP records, a client profile driver must first use [**IOCTL_BTH_SDP_CONNECT**](/windows-hardware/drivers/ddi/bthioctl/ni-bthioctl-ioctl_bth_sdp_connect) to connect to the SDP service of the remote device. A profile driver can then use one of the following IOCTLs to perform the actual SDP record search: -- [**IOCTL\_BTH\_SDP\_ATTRIBUTE\_SEARCH**](/windows-hardware/drivers/ddi/bthioctl/ni-bthioctl-ioctl_bth_sdp_attribute_search) obtains all components of a remote SDP record that fall into a specified SDP attribute range. - -- [**IOCTL\_BTH\_SDP\_SERVICE\_SEARCH**](/windows-hardware/drivers/ddi/bthioctl/ni-bthioctl-ioctl_bth_sdp_service_search) issues an SDP request to the remote device, requesting handles to SDP records of a particular service class or classes. - -- [**IOCTL\_BTH\_SDP\_SERVICE\_ATTRIBUTE\_SEARCH**](/windows-hardware/drivers/ddi/bthioctl/ni-bthioctl-ioctl_bth_sdp_service_attribute_search) combines IOCTL\_BTH\_SDP\_ATTRIBUTE\_SEARCH and IOCTL\_BTH\_SDP\_SERVICE\_ATTRIBUTE\_SEARCH and returns a usable SDP record stream in a single operation. - -Profile drivers can use IOCTL\_BTH\_SDP\_SERVICE\_SEARCH and IOCTL\_BTH\_SDP\_ATTRIBUTE\_SEARCH to reduce the amount of SDP traffic transmitted across a Bluetooth link and can extract necessary information by using a small number of maximum transfer units (MTUs). If neither of these issues is of great concern, it can be more convenient for profile drivers to call IOCTL\_BTH\_SDP\_SERVICE\_ATTRIBUTE\_SEARCH. +- [**IOCTL_BTH_SDP_ATTRIBUTE_SEARCH**](/windows-hardware/drivers/ddi/bthioctl/ni-bthioctl-ioctl_bth_sdp_attribute_search) obtains all components of a remote SDP record that fall into a specified SDP attribute range. -After the profile driver has obtained the *dynamic* protocol/service multiplexer (PSM) for the desired service, it can connect to the remote service by using the **BRB\_L2CA\_OPEN\_CHANNEL** BRB. +- [**IOCTL_BTH_SDP_SERVICE_SEARCH**](/windows-hardware/drivers/ddi/bthioctl/ni-bthioctl-ioctl_bth_sdp_service_search) issues an SDP request to the remote device, requesting handles to SDP records of a particular service class or classes. -**Note**  If the service has a fixed PSM, which many do, L2CAP client profile drivers do not need to use SDP to obtain the PSM. However, L2CAP client profile drivers can still use SDP to get the SDP server attributes. +- [**IOCTL_BTH_SDP_SERVICE_ATTRIBUTE_SEARCH**](/windows-hardware/drivers/ddi/bthioctl/ni-bthioctl-ioctl_bth_sdp_service_attribute_search) combines IOCTL_BTH_SDP_ATTRIBUTE_SEARCH and IOCTL_BTH_SDP_SERVICE_ATTRIBUTE_SEARCH and returns a usable SDP record stream in a single operation. - +Profile drivers can use IOCTL_BTH_SDP_SERVICE_SEARCH and IOCTL_BTH_SDP_ATTRIBUTE_SEARCH to reduce the amount of SDP traffic transmitted across a Bluetooth link and can extract necessary information by using a small number of maximum transfer units (MTUs). If neither of these issues is of great concern, it can be more convenient for profile drivers to call IOCTL_BTH_SDP_SERVICE_ATTRIBUTE_SEARCH. -When the profile driver finishes searching, it should use [**IOCTL\_BTH\_SDP\_DISCONNECT**](/windows-hardware/drivers/ddi/bthioctl/ni-bthioctl-ioctl_bth_sdp_disconnect) to disconnect from the remote SDP server. +After the profile driver has obtained the *dynamic* protocol/service multiplexer (PSM) for the desired service, it can connect to the remote service by using the **BRB_L2CA_OPEN_CHANNEL** BRB. - +> [!NOTE] +> If the service has a fixed PSM, which many do, L2CAP client profile drivers do not need to use SDP to obtain the PSM. However, L2CAP client profile drivers can still use SDP to get the SDP server attributes. +When the profile driver finishes searching, it should use [**IOCTL_BTH_SDP_DISCONNECT**](/windows-hardware/drivers/ddi/bthioctl/ni-bthioctl-ioctl_bth_sdp_disconnect) to disconnect from the remote SDP server. diff --git a/windows-driver-docs-pr/bluetooth/bluetooth-certification.md b/windows-driver-docs-pr/bluetooth/bluetooth-certification.md index 2f50a847ce..143bc3348e 100644 --- a/windows-driver-docs-pr/bluetooth/bluetooth-certification.md +++ b/windows-driver-docs-pr/bluetooth/bluetooth-certification.md @@ -1,23 +1,17 @@ --- title: Bluetooth Certification description: Describes Windows Hardware Certification Program requirements for Bluetooth radios -ms.date: 04/20/2017 +ms.date: 10/06/2022 --- # Bluetooth Certification - -## Where are the Windows Hardware Certification Program requirements for Bluetooth wireless technology? - +## Where are the Windows Hardware Certification Program requirements for Bluetooth wireless technology? The Windows Hardware Certification Program specifies the requirements for hardware and software to work optimally with Windows. For specific details about the Windows Hardware Certification Program requirements for Bluetooth radios and devices, see [Windows Hardware Certification Requirements and Policies](/previous-versions/windows/hardware/cert-program/). For general information about the Windows Hardware Certification Program, see the [Windows Hardware Certification Kit (HCK)](https://go.microsoft.com/fwlink/p/?LinkId=733613) documentation. -## Do Windows 8.1 and Windows 8 have new Bluetooth requirements? - +## Do Windows 8.1 and Windows 8 have new Bluetooth requirements? For Windows 8.1 and Windows 8, the Windows Hardware Certification Program requires Bluetooth radios to support Bluetooth version 4.0 to qualify for a Windows logo. Updated tests are included in the latest version of the HCK. For more information about where to download the HCK, see [Windows Hardware Certification Requirements and Policies](/previous-versions/windows/hardware/cert-program/). - - - diff --git a/windows-driver-docs-pr/bluetooth/bluetooth-core-driver-layer-and-supported-power-transitions.md b/windows-driver-docs-pr/bluetooth/bluetooth-core-driver-layer-and-supported-power-transitions.md index fab7969b05..535659451d 100644 --- a/windows-driver-docs-pr/bluetooth/bluetooth-core-driver-layer-and-supported-power-transitions.md +++ b/windows-driver-docs-pr/bluetooth/bluetooth-core-driver-layer-and-supported-power-transitions.md @@ -1,18 +1,18 @@ --- -title: Bluetooth Core Driver Layer and Supported Power Transitions -description: The following table summarizes device and system power states that the Bluetooth core driver supports. -ms.date: 04/20/2017 +title: Bluetooth core driver layer and supported power transitions +description: Summarizes device and system power states that the Bluetooth core driver supports. +ms.date: 10/07/2022 --- -# Bluetooth Core Driver Layer and Supported Power Transitions +# Bluetooth core driver layer and supported power transitions -The following table summarizes device and system power states that the Bluetooth core driver supports. A "sleep" state is used throughput this section and its subtopics to describe a very low power state in which the Bluetooth radio’s internal settings and configurations are persistent. +The following table summarizes device and system power states that the Bluetooth core driver supports. A "sleep" state is used throughput this section and its subtopics to describe a very low power state in which the Bluetooth radio's internal settings and configurations are persistent. -## Device Power States +## Device power states | System power states | Device power state D0 | Device power state D2 | Device power state D3 | -|----|----|----|----| -| | D0 (Active) | D2 (sleep) – some power is maintained to the Bluetooth chip for persisting its internal state. | D3 (Off) - Power is removed (*) | +|--|--|--|--| +| | D0 (Active) | D2 (sleep) – some power is maintained to the Bluetooth chip for persisting its internal state. | D3 (Off) - Power is removed (*) | | S0 (Active) | Active | Sleep if armed for wake | Radio RM off | | S1 | N/A | N/A | N/A | | S2 | N/A | N/A | N/A | @@ -32,7 +32,7 @@ Guidelines for system state support for SoC systems: This is the state when a client application is actively using Bluetooth functionality. -## Low Duty Cycle/Sleep (S0/D2) +## Low duty cycle/sleep (S0/D2) This is the most common state in which the system is effectively on (in S0), but the driver is in the D2 state – the controller is throttled down to a lower power state. While in this state, a controller can resume to the active state (D0) rather quickly without affecting the end-user experience. @@ -43,23 +43,23 @@ Another example is in the initial condition when there are no associations – t Common and critical scenarios in this state: 1. Have no associations (i.e. no pairings with Bluetooth devices) -2. Have an association, be connected but in idle -3. Have an association but be disconnected +1. Have an association, be connected but in idle +1. Have an association but be disconnected Later subtopic provide further details on the mechanisms of entering idle and resuming to active. This state also becomes the primary state in an AOAC (Always On Always Connected) system. -## System is On but Device is Off (S0/D3) +## System is on but device is off (S0/D3) This state is currently only supported for Radio Management when the radio is in "off" mode. The state will incur a longer latency to restore a Bluetooth controller to its active state where the process includes but is not limited to device level initialization and configuration, as well as host and device initialization by the Bluetooth core driver. -## System Remote Wake-able (Sx/D2) +## System remote wake-able (Sx/D2) The support for this Sx remains unchanged for Windows 8.1, and this particular state is used to enable waking the system from a HID device. While in D2, the Bluetooth chip continues to have power so its internal volatile settings and configuration remain persistent. This capability is optional. -## System Off (Sx/D3) +## System off (Sx/D3) The system is off, and the Bluetooth radio is assumed to be off or in a low power state. In some Sx states (except shutdown), the driver stack is still in memory (i.e. it remains loaded). -## Radio Management +## Radio management Going forward, Radio Management (RM) will be standardized for Bluetooth 4.0 radios. The Bluetooth stack will send down an HCI\_RESET command, which the radio is expected to respond by putting the radio in no transmission mode and the device in D3 power state. The stack will then surprise remove all child devnodes, effectively putting the radio in "airplane" mode. The serial bus driver will stay loaded while in the Radio off state, so it can receive a request from the stack to turn the radio back on. The inbox stack will handle the re-enumeration of devnodes. For more details on implementation of radio management, please refer to the [Bluetooth Software Radio Switch Function Prototypes](bluetooth-software-radio-switch-function-prototypes.md). diff --git a/windows-driver-docs-pr/bluetooth/bluetooth-driver-stack.md b/windows-driver-docs-pr/bluetooth/bluetooth-driver-stack.md index a5e25d7db0..682cbae815 100644 --- a/windows-driver-docs-pr/bluetooth/bluetooth-driver-stack.md +++ b/windows-driver-docs-pr/bluetooth/bluetooth-driver-stack.md @@ -1,73 +1,59 @@ --- -title: Bluetooth Driver Stack -description: Bluetooth Driver Stack +title: Bluetooth driver stack +description: Bluetooth driver stack keywords: - Bluetooth WDK , driver stack - driver stacks WDK Bluetooth - stacks WDK Bluetooth -ms.date: 04/20/2017 +ms.date: 10/10/2022 --- -# Bluetooth Driver Stack - +# Bluetooth driver stack The Bluetooth driver stack comprises the core portion of the support provided by Microsoft for the Bluetooth protocol. With this stack, Bluetooth-enabled devices can locate each other and establish connections. Across such connections, the devices can exchange data and interact with one another through various applications. The following image shows the modules within the Bluetooth driver stack, along with possible custom user-mode and kernel-mode drivers not included in Windows Vista and later. These custom drivers are known as profile drivers. -![diagram illustrating the bluetooth driver stack.](images/bluetooth-architecture.png) - -- **User-mode** - - **User-mode application**- A user-mode application that accesses the Bluetooth driver stack through published APIs. For more information, see [About Bluetooth](/windows/win32/bluetooth/about-bluetooth) in the Windows SDK documentation. - - **Note**  User-mode applications should link against *BthProps.lib*, instead of *IrProps.lib*, in order to use APIs, such as [**BluetoothSetLocalServiceInfo**](/windows/win32/api/bluetoothapis/nf-bluetoothapis-bluetoothsetlocalserviceinfo). - - - -- **Examples of profile drivers** - - **WAP Kernel Mode Driver**- The Wireless Application Protocol (WAP) component is an example of a profile driver that communicates between the Windows networking stack and BthPort, accessing the L2CAP interface and, optionally, the SDP interface contained in L2CAP. Other possible profiles include the Advanced Audio Distribution profile (A2DP), A/V Remote Control profile (AVRCP), Generic A/V Distribution profile (GAVDP), and Common ISDN Access (CIP) profile. - - **Audio Kernel Mode Driver**- An example of a profile driver that communicates between the Windows audio stack and BthPort, accessing the SCO interfaces contained in the latter. Possible profiles include the Hands Free profile (HFP), Headset profile (HSP), Cordless Telephony profile (CTP), and Intercom profile (ICP). - **Note**  This profile driver is included with Windows beginning with Windows 8. - - - - - **Bluetooth LE Heart Rate Monitor Profile**- An example of a Bluetooth LE profile driver that communicates with the Bluetooth Low Energy (LE) API. -- **Bluetooth driver stack components** - - **IrProps**- A component that is used for backward compatibility for profile drivers that are created for the first version of the Bluetooth driver stack. +:::image type="content" source="images/bluetooth-architecture.png" alt-text="Diagram showing the bluetooth driver stack."::: - **Note**  **IrProps** is provided only for backward compatibility. Use the **BthProps** component for new development. +- **User-mode** + - **User-mode application**- A user-mode application that accesses the Bluetooth driver stack through published APIs. For more information, see [About Bluetooth](/windows/win32/bluetooth/about-bluetooth) in the Windows SDK documentation. - + User-mode applications should link against *BthProps.lib*, instead of *IrProps.lib*, in order to use APIs, such as **[BluetoothSetLocalServiceInfo](/windows/win32/api/bluetoothapis/nf-bluetoothapis-bluetoothsetlocalserviceinfo)**. - - **BthProps**- A component that contains the implementation of the Bluetooth user interface along with implementation of the Bluetooth APIs that user-mode applications access. This component sends inquiries to BthServ through remote procedure calls (RPC). Additionally, BthProps performs pin exchanges with BthPort through private IOCTLs. Note that BthProps runs on any system with a Bluetooth-enabled radio. - - **BthServ**- A service that is responsible for caching and forwarding inquiry data to Bthport. - - **BthCi**- The Bluetooth class installer. - - **WshBth**- The Bluetooth Windows socket helper component. WshBth is called by the Windows sockets layer to perform socket operations. WshBth primarily calls into RfComm through the TDI interface. WshBth also calls into BthServ to perform remote device inquiries and into BthPort to perform local radio inquiries. - - **FSquirt**- A nonextensible Object Exchange (OBEX) component that allows users to send and receive files across an open Bluetooth connection. OBEX communicates with remote devices through RFCOMM that uses the WshBth component. - - **BthPrint**- A component that implements the Hardcopy Cable Replacement Profile (HCRP). This component allows the print system to send data to and receive data from Bluetooth-enabled printers. BthPrint communicates with the SDP interface in BthPort to query remote printers and the L2CAP interface in BthPort to send and receive data. - - **HidBth**- The component that implements the Human Interface Device (HID) profile. HidBth also communicates with the L2CAP and SDP interfaces in BthPort. HidBth connects to the HID stack much like USB HID module does. - - **BthPan**- The component that implements the Personal Area Network (PAN) profile, providing TCP connections across an open Bluetooth connection. In Windows Vista and Windows XP, BthPan only supports outgoing connections. BthPan is also a client of the BthPort component and uses both the L2CAP and SDP interfaces. - - **RfComm**- The component that implements the Bluetooth serial cable emulation protocol. RfComm also uses the L2CAP and SDP interfaces found in BthPort. The upper edge of RfComm exposes the TDI interface, allowing this component to appear to be a networking transport. This is how WshBth connects to Bluetooth to send and receive data from user-mode APIs. +- **Examples of profile drivers** + - **WAP Kernel Mode Driver**- The Wireless Application Protocol (WAP) component is an example of a profile driver that communicates between the Windows networking stack and BthPort, accessing the L2CAP interface and, optionally, the SDP interface contained in L2CAP. Other possible profiles include the Advanced Audio Distribution profile (A2DP), A/V Remote Control profile (AVRCP), Generic A/V Distribution profile (GAVDP), and Common ISDN Access (CIP) profile. + - **Audio Kernel Mode Driver**- An example of a profile driver that communicates between the Windows audio stack and BthPort, accessing the SCO interfaces contained in the latter. Possible profiles include the Hands Free profile (HFP), Headset profile (HSP), Cordless Telephony profile (CTP), and Intercom profile (ICP). This profile driver is included with Windows beginning with Windows 8. - User-mode applications can access RfComm using the Winsock interfaces described in the Windows SDK. + - **Bluetooth LE Heart Rate Monitor Profile**- An example of a Bluetooth LE profile driver that communicates with the Bluetooth Low Energy (LE) API. +- **Bluetooth driver stack components** + - **IrProps**- A component that is used for backward compatibility for profile drivers that are created for the first version of the Bluetooth driver stack. **IrProps** is provided only for backward compatibility. Use the **BthProps** component for new development. - - **BthModem**- The component that implements virtual COM ports and dial-up networking (DUN). BthModem directs all I/O and control operations to RfComm through a TDI interface. The upper edge of BthModem communicates with *Serial.sys* to give the appearance of being a wireless COM port. - **Note**  This component is not available in Windows RT. + - **BthProps**- A component that contains the implementation of the Bluetooth user interface along with implementation of the Bluetooth APIs that user-mode applications access. This component sends inquiries to BthServ through remote procedure calls (RPC). Additionally, BthProps performs pin exchanges with BthPort through private IOCTLs. Note that BthProps runs on any system with a Bluetooth-enabled radio. + - **BthServ**- A service that is responsible for caching and forwarding inquiry data to Bthport. + - **BthCi**- The Bluetooth class installer. + - **WshBth**- The Bluetooth Windows socket helper component. WshBth is called by the Windows sockets layer to perform socket operations. WshBth primarily calls into RfComm through the TDI interface. WshBth also calls into BthServ to perform remote device inquiries and into BthPort to perform local radio inquiries. + - **FSquirt**- A nonextensible Object Exchange (OBEX) component that allows users to send and receive files across an open Bluetooth connection. OBEX communicates with remote devices through RFCOMM that uses the WshBth component. + - **BthPrint**- A component that implements the Hardcopy Cable Replacement Profile (HCRP). This component allows the print system to send data to and receive data from Bluetooth-enabled printers. BthPrint communicates with the SDP interface in BthPort to query remote printers and the L2CAP interface in BthPort to send and receive data. + - **HidBth**- The component that implements the Human Interface Device (HID) profile. HidBth also communicates with the L2CAP and SDP interfaces in BthPort. HidBth connects to the HID stack much like USB HID module does. + - **BthPan**- The component that implements the Personal Area Network (PAN) profile, providing TCP connections across an open Bluetooth connection. In Windows Vista and Windows XP, BthPan only supports outgoing connections. BthPan is also a client of the BthPort component and uses both the L2CAP and SDP interfaces. + - **RfComm**- The component that implements the Bluetooth serial cable emulation protocol. RfComm also uses the L2CAP and SDP interfaces found in BthPort. The upper edge of RfComm exposes the TDI interface, allowing this component to appear to be a networking transport. This is how WshBth connects to Bluetooth to send and receive data from user-mode APIs. - + User-mode applications can access RfComm using the Winsock interfaces described in the Windows SDK. - - **BthEnum**- The Bluetooth bus driver. BthEnum communicates with the Plug and Play (PnP) manager to create and destroy device objects used to enable Bluetooth services. BthEnum creates a PDO for every service that a connected remote device supports. For example, when a user connects a Bluetooth-enabled mouse, Windows will discover that the mouse supports the Bluetooth HID service and creates a PDO for the HID service that causes the PnP manager to load HidBth. + - **BthModem**- The component that implements virtual COM ports and dial-up networking (DUN). BthModem directs all I/O and control operations to RfComm through a TDI interface. The upper edge of BthModem communicates with *Serial.sys* to give the appearance of being a wireless COM port. - **Note**  BthEnum will not create PDOs for services that appear in the **UnsupportedServices** registry key as specified in *Bth.inf*. + - **BthEnum**- The Bluetooth bus driver. BthEnum communicates with the Plug and Play (PnP) manager to create and destroy device objects used to enable Bluetooth services. BthEnum creates a PDO for every service that a connected remote device supports. For example, when a user connects a Bluetooth-enabled mouse, Windows will discover that the mouse supports the Bluetooth HID service and creates a PDO for the HID service that causes the PnP manager to load HidBth. - + > [!NOTE] + > BthEnum will not create PDOs for services that appear in the **UnsupportedServices** registry key as specified in *Bth.inf*. - - **BthLEEnum**- The Bluetooth Low Energy (LE) bus driver. BthLEEnum implements the ATT protocol and the GATT profile. It is also responsible for creating PDOs to represent the remote devices and their primary services. + - **BthLEEnum**- The Bluetooth Low Energy (LE) bus driver. BthLEEnum implements the ATT protocol and the GATT profile. It is also responsible for creating PDOs to represent the remote devices and their primary services. - - **BthPort**- A minidriver loaded by the BthUsb miniport. BthPort provides four components: - - The HCI component communicates to the local Bluetooth-enabled radio through the Host Controller Interface (HCI) defined in the Bluetooth specification. Because all Bluetooth-enabled radios implement the HCI specification, BthPort is able to communicate with any Bluetooth-enabled radio, regardless of the manufacturer or model. - - The SCO component implements the Synchronous Connection-Oriented (SCO) protocol. This protocol supports creating point-to-point connections to a remote device. SCO clients communicate with the SCO interface by [building and sending](building-and-sending-a-brb.md) Bluetooth request blocks (BRBs). - - L2CAP implements the Bluetooth logical link control and adaptation protocol. This protocol supports creating a lossless channel to a remote device. L2CAP clients communicate with the L2CAP interface by building and sending Bluetooth request blocks (BRBs). - - SDP implements the Bluetooth Service Discovery Protocol. - - **BthUsb.sys**- The miniport that abstracts the bus interface from **BthPort**. + - **BthPort**- A minidriver loaded by the BthUsb miniport. BthPort provides four components: + 1. The HCI component communicates to the local Bluetooth-enabled radio through the Host Controller Interface (HCI) defined in the Bluetooth specification. Because all Bluetooth-enabled radios implement the HCI specification, BthPort is able to communicate with any Bluetooth-enabled radio, regardless of the manufacturer or model. + 1. The SCO component implements the Synchronous Connection-Oriented (SCO) protocol. This protocol supports creating point-to-point connections to a remote device. SCO clients communicate with the SCO interface by [building and sending](building-and-sending-a-brb.md) Bluetooth request blocks (BRBs). + 1. L2CAP implements the Bluetooth logical link control and adaptation protocol. This protocol supports creating a lossless channel to a remote device. L2CAP clients communicate with the L2CAP interface by building and sending Bluetooth request blocks (BRBs). + 1. SDP implements the Bluetooth Service Discovery Protocol. + - **BthUsb.sys**- The miniport that abstracts the bus interface from **BthPort**. diff --git a/windows-driver-docs-pr/bluetooth/bluetooth-host-radio-support.md b/windows-driver-docs-pr/bluetooth/bluetooth-host-radio-support.md index 18ebdf9e1c..66dfbd8c2d 100644 --- a/windows-driver-docs-pr/bluetooth/bluetooth-host-radio-support.md +++ b/windows-driver-docs-pr/bluetooth/bluetooth-host-radio-support.md @@ -1,7 +1,7 @@ --- title: Bluetooth host radio support description: Provides a list of questions and answers about Bluetooth host radio support in Windows -ms.date: 04/20/2017 +ms.date: 10/07/2022 --- # Bluetooth Host Radio Support @@ -10,7 +10,7 @@ This topic provides answers to typical questions about Bluetooth Radio support. ## Bluetooth host controllers supported in Windows -With Windows, a Bluetooth radio can be packaged as an external dongle or embedded inside a computer but it must be connected to one of the computer’s USB ports. The Bluetooth stack that is included with Windows 7 and Windows Vista does not support Bluetooth radio connections over PCI, I2C, serial, Secure Digital I/O (SDIO), CompactFlash, or PC Card interfaces. In Windows 8 and Windows 8.1, radios connected over alternate transports can be added via a third-party bus driver. Refer to the Extensible Transport sections of the [Bluetooth Devices Reference](/windows-hardware/drivers/ddi/_bltooth/) for more information. +With Windows, a Bluetooth radio can be packaged as an external dongle or embedded inside a computer but it must be connected to one of the computer's USB ports. The Bluetooth stack that is included with Windows 7 and Windows Vista does not support Bluetooth radio connections over PCI, I2C, serial, Secure Digital I/O (SDIO), CompactFlash, or PC Card interfaces. In Windows 8 and Windows 8.1, radios connected over alternate transports can be added via a third-party bus driver. Refer to the Extensible Transport sections of the [Bluetooth Devices Reference](/windows-hardware/drivers/ddi/_bltooth/) for more information. ## Forcing the Bluetooth stack to load if Windows cannot match the device ID (Windows Vista) @@ -23,8 +23,8 @@ A new Bluetooth radio might not match any of the device IDs in the Bluetooth INF The following procedure uses Device Manager to force the Bluetooth stack to load for a new radio: 1. Run the Control Panel Device Manager application and identify the Bluetooth radio on the list of devices. -2. To run the Update Driver Software Wizard, right-click the Bluetooth radio item and select **Update Driver Software**. -3. Use the wizard to force the Bluetooth stack to install. +1. To run the Update Driver Software Wizard, right-click the Bluetooth radio item and select **Update Driver Software**. +1. Use the wizard to force the Bluetooth stack to install. For a detailed description of this procedure, see [Appendix A: How to Install an In-Box Bluetooth Driver on New Hardware in Windows Vista](bluetooth-faq--appendix-a.yml). @@ -50,9 +50,9 @@ The Control Panel Bluetooth application was incorporated into Devices and Printe If the Bluetooth icon does not appear in the taskbar, it could be due to one or more of the following reasons: -* The Bluetooth radio is turned off. -* The Bluetooth radio is in emulation mode. -* In the **Bluetooth Settings** dialog, the **Show the Bluetooth icon in the notification area** check box is not selected. +- The Bluetooth radio is turned off. +- The Bluetooth radio is in emulation mode. +- In the **Bluetooth Settings** dialog, the **Show the Bluetooth icon in the notification area** check box is not selected. ## Windows support for Bluetooth radio firmware updates @@ -66,7 +66,7 @@ Windows includes support for vendor-specific pass-through commands. These kernel Windows supports vendor-supplied Bluetooth profiles. The GUIDs for those profiles that have been standardized by the Bluetooth SIG are included in the in box INF file (Bth.inf). -When users pair a Bluetooth device with a computer, the device’s profiles are compared to the profiles that are listed in Bth.inf. If the device profile does not match one of those profiles, users receive a dialog box that asks them to provide appropriate vendor software. +When users pair a Bluetooth device with a computer, the device's profiles are compared to the profiles that are listed in Bth.inf. If the device profile does not match one of those profiles, users receive a dialog box that asks them to provide appropriate vendor software. Vendors that want a vendor-specific profile must use their own GUID and reference it in a vendor-specific INF file. This INF file can use Include and Needs directives to reference the appropriate Bth.inf sections and directives. For an example of a vendor-specific INF file, see [Appendix B: An Example of a Vendor-Provided INF File for Use in Windows Vista](bluetooth-faq--appendix-b.yml). @@ -79,22 +79,22 @@ The Bluetooth stack included with Windows provides in-box support for only some The following table lists the profiles in Bth.inf that Windows supports. -|Service ID|Description| -|----|----| -|{00001101-0000-1000-8000-00805f9b34fb}|SPP| -|{00001103-0000-1000-8000-00805f9b34fb}|DUN -|{00001124-0000-1000-8000-00805f9b34fb}|HID| -|{00001126-0000-1000-8000-00805f9b34fb}|HCRP| +| Service ID | Description | +|--|--| +| {00001101-0000-1000-8000-00805f9b34fb} | SPP | +| {00001103-0000-1000-8000-00805f9b34fb} | DUN | +| {00001124-0000-1000-8000-00805f9b34fb} | HID | +| {00001126-0000-1000-8000-00805f9b34fb} | HCRP | ### Windows Bluetooth Profiles -For a Bluetooth-enabled device or accessory to work with your PC that’s running Windows 10, the device needs to use one of the supported Bluetooth profiles. See the most current list at [Supported Bluetooth profiles](https://support.microsoft.com/help/10568/windows-10-supported-bluetooth-profiles). +For a Bluetooth-enabled device or accessory to work with your PC that's running Windows 10, the device needs to use one of the supported Bluetooth profiles. See the most current list at [Supported Bluetooth profiles](https://support.microsoft.com/help/10568/windows-10-supported-bluetooth-profiles). If IHVs do not want Windows to automatically generate a PDO for their device, they can add the service GUID to the list of unsupported services. For examples, see Bth.inf. ## How Group Policy can block Bluetooth radio installation -For details on how to use Group Policy to block the installation of Bluetooth radios, see the “Prevent installation of prohibited devices” section of [Step-by-Step Guide to Controlling Device Installation and Usage with Group Policy](/previous-versions/dotnet/articles/bb530324(v=msdn.10)). +For details on how to use Group Policy to block the installation of Bluetooth radios, see the "Prevent installation of prohibited devices" section of [Step-by-Step Guide to Controlling Device Installation and Usage with Group Policy](/previous-versions/dotnet/articles/bb530324(v=msdn.10)). Use the following compatible IDs for the Bluetooth radio: @@ -102,7 +102,7 @@ USB\\Class\_E0 (for USB based radios) MS\_BTHX\_BTHMINI (for non-USB radios) > [!NOTE] -> This won’t remove Bluetooth driver support if it has already been installed. Also, this policy needs to be applied to the preinstall image. +> This won't remove Bluetooth driver support if it has already been installed. Also, this policy needs to be applied to the preinstall image. ## How to change the Device ID Profile record published by Windows @@ -110,46 +110,9 @@ The Device ID Profile defines an SDP record that can be used to provide identity Windows also publishes a local Device ID record to identify the Windows device to remote Bluetooth devices. The default values can be adjusted by OEMs to better identify their specific Windows device. These values are defined as in the following table under the HKLM\\System\\CCS\\services\\BTHPORT\\Parameters registry key: - ------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

ValueName

Type

Description

Default Value

DIDVendorIDSource

DWORD

0x01 = Bluetooth SIG namespace

-

0x02 = USB Forum namespace

0x01

DIDVendorID

DWORD

OEM specified VendorID

0x06 – Microsoft Vendor ID

DIDProductID

DWORD

OEM specified ProductID

0x01 – Microsoft Windows

DIDVersion

DWORD

OEM specified product version

0x0800 – Windows 8

+| ValueName | Type | Description | Default Value | +|--|--|--|--| +| DIDVendorIDSource | DWORD | 0x01 = Bluetooth SIG namespace
0x02 = USB Forum namespace | 0x01 | +| DIDVendorID | DWORD | OEM specified VendorID | 0x06 – Microsoft Vendor ID | +| DIDProductID | DWORD | OEM specified ProductID | 0x01 – Microsoft Windows | +| DIDVersion | DWORD | OEM specified product version | 0x0800 – Windows 8 | diff --git a/windows-driver-docs-pr/bluetooth/bluetooth-ioctls2.md b/windows-driver-docs-pr/bluetooth/bluetooth-ioctls2.md index 7f8aee8586..8fb4544a32 100644 --- a/windows-driver-docs-pr/bluetooth/bluetooth-ioctls2.md +++ b/windows-driver-docs-pr/bluetooth/bluetooth-ioctls2.md @@ -11,24 +11,22 @@ ms.date: 04/20/2017 # Bluetooth IOCTLs - The Bluetooth driver stack provides profile drivers with several IOCTLs to gather information about: -- The local Bluetooth radio and system. +- The local Bluetooth radio and system. -- Remote Bluetooth devices. +- Remote Bluetooth devices. -- The device that caused the Plug and Play (PnP) Manager to load a profile driver. +- The device that caused the Plug and Play (PnP) Manager to load a profile driver. -To gather information about the local Bluetooth radio and system, a profile driver uses [**IOCTL\_BTH\_GET\_LOCAL\_INFO**](/windows-hardware/drivers/ddi/bthioctl/ni-bthioctl-ioctl_bth_get_local_info). After the IOCTL returns, its **AssociatedIrp.SystemBuffer** member contains a pointer to a [**BTH\_LOCAL\_RADIO\_INFO**](/windows-hardware/drivers/ddi/bthioctl/ns-bthioctl-_bth_local_radio_info) structure that contains information about the local Bluetooth radio and system, including flags that indicate whether the local radio can be discovered and connected to. The returned BTH\_LOCAL\_RADIO\_INFO structure contains a [BTH\_DEVICE\_INFO](/windows/win32/api/bthdef/ns-bthdef-bth_device_info) structure, which contains system-specific information, and a [**BTH\_RADIO\_INFO**](/windows-hardware/drivers/ddi/bthioctl/ns-bthioctl-_bth_radio_info) structure, which contains local radio-specific information. +To gather information about the local Bluetooth radio and system, a profile driver uses [**IOCTL_BTH_GET_LOCAL_INFO**](/windows-hardware/drivers/ddi/bthioctl/ni-bthioctl-ioctl_bth_get_local_info). After the IOCTL returns, its **AssociatedIrp.SystemBuffer** member contains a pointer to a [**BTH_LOCAL_RADIO_INFO**](/windows-hardware/drivers/ddi/bthioctl/ns-bthioctl-_bth_local_radio_info) structure that contains information about the local Bluetooth radio and system, including flags that indicate whether the local radio can be discovered and connected to. The returned BTH_LOCAL_RADIO_INFO structure contains a [BTH_DEVICE_INFO](/windows/win32/api/bthdef/ns-bthdef-bth_device_info) structure, which contains system-specific information, and a [**BTH_RADIO_INFO**](/windows-hardware/drivers/ddi/bthioctl/ns-bthioctl-_bth_radio_info) structure, which contains local radio-specific information. -To gather information about a specific remote Bluetooth device, a profile driver uses [**IOCTL\_BTH\_GET\_RADIO\_INFO**](/windows-hardware/drivers/ddi/bthioctl/ni-bthioctl-ioctl_bth_get_radio_info). After the IOCTL returns, its **AssociatedIrp.SystemBuffer** member contains a pointer to a BTH\_RADIO\_INFO structure that provides information about the specific remote radio, including whether the remote radio can be discovered and connected to. +To gather information about a specific remote Bluetooth device, a profile driver uses [**IOCTL_BTH_GET_RADIO_INFO**](/windows-hardware/drivers/ddi/bthioctl/ni-bthioctl-ioctl_bth_get_radio_info). After the IOCTL returns, its **AssociatedIrp.SystemBuffer** member contains a pointer to a BTH_RADIO_INFO structure that provides information about the specific remote radio, including whether the remote radio can be discovered and connected to. -To gather information about all remote radios that have been discovered, a profile driver uses [**IOCTL\_BTH\_GET\_DEVICE\_INFO**](/windows-hardware/drivers/ddi/bthioctl/ni-bthioctl-ioctl_bth_get_device_info). After the IOCTL returns, its **AssociatedIrp.SystemBuffer** member contains a pointer to a [**BTH\_DEVICE\_INFO\_LIST**](/windows-hardware/drivers/ddi/bthioctl/ns-bthioctl-_bth_device_info_list) structure that contains an array of BTH\_DEVICE\_INFO structures. The BTH\_DEVICE\_INFO\_LIST structure contains one array entry for each discovered remote radio. The user-mode [BluetoothGetDeviceInfo](/windows/win32/api/bluetoothapis/nf-bluetoothapis-bluetoothgetdeviceinfo) API uses this functionality to return information about all remote radios. +To gather information about all remote radios that have been discovered, a profile driver uses [**IOCTL_BTH_GET_DEVICE_INFO**](/windows-hardware/drivers/ddi/bthioctl/ni-bthioctl-ioctl_bth_get_device_info). After the IOCTL returns, its **AssociatedIrp.SystemBuffer** member contains a pointer to a [**BTH_DEVICE_INFO_LIST**](/windows-hardware/drivers/ddi/bthioctl/ns-bthioctl-_bth_device_info_list) structure that contains an array of BTH_DEVICE_INFO structures. The BTH_DEVICE_INFO_LIST structure contains one array entry for each discovered remote radio. The user-mode [BluetoothGetDeviceInfo](/windows/win32/api/bluetoothapis/nf-bluetoothapis-bluetoothgetdeviceinfo) API uses this functionality to return information about all remote radios. -To gather information about the remote device that caused the PnP Manager to load it, a profile driver uses [**IOCTL\_INTERNAL\_BTHENUM\_GET\_DEVINFO**](/windows-hardware/drivers/ddi/bthioctl/ni-bthioctl-ioctl_internal_bthenum_get_devinfo). After the IOCTL returns, its **AssociatedIrp.SystemBuffer** member contains a pointer to a BTH\_DEVICE\_INFO structure that contains information about the remote device, including its Bluetooth device address, device state, and its class-of-device (CoD) settings. +To gather information about the remote device that caused the PnP Manager to load it, a profile driver uses [**IOCTL_INTERNAL_BTHENUM_GET_DEVINFO**](/windows-hardware/drivers/ddi/bthioctl/ni-bthioctl-ioctl_internal_bthenum_get_devinfo). After the IOCTL returns, its **AssociatedIrp.SystemBuffer** member contains a pointer to a BTH_DEVICE_INFO structure that contains information about the remote device, including its Bluetooth device address, device state, and its class-of-device (CoD) settings. -A profile driver uses [**IOCTL\_INTERNAL\_BTHENUM\_GET\_ENUMINFO**](/windows-hardware/drivers/ddi/bthioctl/ni-bthioctl-ioctl_internal_bthenum_get_enuminfo) to obtain information about the underlying device and service that caused the PnP manager to load the profile driver. After the IOCTL returns, its **AssociatedIrp.SystemBuffer** member contains a pointer to a [**BTH\_ENUMERATOR\_INFO**](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_bth_enumerator_info) structure that contains vendor-provided information about the device, including the port number, device flags, vendor ID, and product ID. +A profile driver uses [**IOCTL_INTERNAL_BTHENUM_GET_ENUMINFO**](/windows-hardware/drivers/ddi/bthioctl/ni-bthioctl-ioctl_internal_bthenum_get_enuminfo) to obtain information about the underlying device and service that caused the PnP manager to load the profile driver. After the IOCTL returns, its **AssociatedIrp.SystemBuffer** member contains a pointer to a [**BTH_ENUMERATOR_INFO**](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_bth_enumerator_info) structure that contains vendor-provided information about the device, including the port number, device flags, vendor ID, and product ID. For more information about using Bluetooth IOCTLs and BRBs, see [Building and Sending a BRB](building-and-sending-a-brb.md). - diff --git a/windows-driver-docs-pr/bluetooth/bluetooth-low-energy-audio.md b/windows-driver-docs-pr/bluetooth/bluetooth-low-energy-audio.md new file mode 100644 index 0000000000..a4542b8ed0 --- /dev/null +++ b/windows-driver-docs-pr/bluetooth/bluetooth-low-energy-audio.md @@ -0,0 +1,607 @@ +--- +title: Bluetooth Low Energy (LE) Audio +description: This article provides an overview of Bluetooth LE Audio introduced in Windows 11 version 22H2 (KB5026446). +ms.date: 07/27/2023 +--- + +# Bluetooth Low Energy (LE) Audio + +This article provides an overview of Bluetooth LE Audio introduced in Windows 11 version 22H2 (KB5026446). + +## Introduction + +Bluetooth LE Audio enables streaming unicast or broadcast audio to Bluetooth LE devices over an isochronous transport. As of version 5.3 of the Bluetooth core specification, there's no standard defined host controller interface (HCI) for host platforms to send and receive isochronous data to and from the Bluetooth controller. This document defines the Windows Bluetooth vendor specific audio path (VSAP) to allow platforms to use vendor-specific solutions to enable Bluetooth LE Audio streaming. The VSAP software interface uses Windows [audio class extensions](../audio/acx-audio-class-extensions-overview.md) (ACX) and more interface properties defined in this document. + +### Terminology and prerequisites + +In addition to the terms defined in this table, this document also references terms defined by Windows audio class extensions. + +| Term | Definition | +|---|---| +| LE audio | Short for Bluetooth LE Audio | +| Classic audio | Bluetooth audio streaming that uses the hands-free profile (HFP) and advanced audio distribution profile (A2DP) | +| Audio Device | A single remote Bluetooth LE Audio device or set of Bluetooth LE Audio devices that together compose a single audio endpoint from the perspective of Windows. | +| BAP | The [Basic Audio Profile](https://www.bluetooth.com/specifications/specs/basic-audio-profile-1-0-1/) defines how devices can distribute and consume audio using Bluetooth Low Energy (LE) communications. | +| TMAP | The [Telephony and Media Audio Profile](https://www.bluetooth.com/specifications/tmap-1-0/) specifies interoperable configurations of the lower-level audio services and profiles. | +| ASCS | The [Audio Stream Control Service](https://www.bluetooth.com/specifications/specs/audio-stream-control-service/) defines a standard way for Bluetooth LE Audio devices to configure and establish unicast audio streams. | +| PACS | The [Published Audio Capabilities Service](https://www.bluetooth.com/specifications/specs/published-audio-capabilities-service-1-0-1/) defines a standard way for Bluetooth LE Audio devices to report its supported audio codec capabilities. | +| CIS | The Connected Isochronous Streams transport is used to send and receive unicast audio data between Bluetooth LE devices. | +| BIS | The Broadcast Isochronous Stream transport is used for connectionless audio data transfers. | +| ACX | Short for audio class extensions, which is the driver model required by all audio drivers to support for Bluetooth LE Audio on Windows. | +| Streaming circuits | One or more **ACXCIRCUIT** objects created by the Vendor Specific Audio Driver Stack for its streaming path. | +| Profile circuit | An **ACXCIRCUIT** object created by the Bluetooth LE Audio profile implementation on Windows. This **ACXCIRCUIT** serves as the head circuit as defined in the ACX specification and isn't a streaming circuit. | + +This document assumes familiarity with the previously defined terms and the following HCI commands defined in the [Bluetooth Core 5.3 specification](https://www.bluetooth.com/specifications/specs/core-specification-5-3/): + +- HCI_Read_Local_Supported_Codecs (v2) +- HCI_Read_Local_Supported_Codec_Capabilities +- HCI_LE_Set_CIG_Parameters +- HCI_LE_Create_CIS +- HCI_Configure_Data_Path +- HCI_LE_Setup_ISO_Data_Path +- HCI_LE_Remove_ISO_Data_Path +- HCI_LE_Remove_CIG + +Bluetooth LE Audio VSAP requires the audio drivers to use the ACX framework. Adopting ACX for Bluetooth LE Audio provides several advantages, such as: + +- Supports the preferred audio driver model for Windows going forward. +- Uses ACX's native support for multi stack audio solutions without requiring a dedicated DDI between drivers. +- Doesn't require IHV audio drivers to relay requests from the audio system to the Bluetooth stack. Instead, ACX can send requests directly to the Bluetooth stack via the profile circuit. + +## Architecture + +### Definitions + +The following components are involved in the different VSAP architecture variants. + +#### Windows ACX framework + +This component enables support for a multi-stack audio endpoint. For Bluetooth LE Audio, the software components that compose an audio endpoint are the vendor specific audio driver stack and the Windows Bluetooth LE Audio profile. + +#### Vendor specific audio driver stack + +This vendor specific component is responsible for sending and receiving Bluetooth LE Audio data to and from a Bluetooth controller via a vendor defined audio interface. It shall consist of at a minimum an ACX streaming driver to manage the incoming and outgoing audio data. More ACX drivers may be included if they're necessary parts of the multi circuit ACX audio endpoint. This component is also referred to as the IHV ACX Streaming Driver in this document. + +#### Windows Bluetooth LE Audio profile + +This component contains the implementation of the Basic Audio Profile (BAP), Volume Control Profile, and Microphone Control Profile. It's responsible for creating the head **[ACXCIRCUIT](/windows-hardware/drivers/audio/acx-summary-of-objects#acx-circuit)** for each Bluetooth LE Audio device or set of devices paired to Windows, reporting audio formats reported by the remote device and Bluetooth controller, and manages the state of isochronous channels and groups. + +#### Windows Bluetooth core stack + +This component provides an interface to allow the Windows Bluetooth LE Audio Profile to query supported codec capabilities from the local Bluetooth controller and manage the state of isochronous channels and groups. + +#### LC3 codec + +This subcomponent is responsible for translating between compressed LC3 audio and PCM audio. It shall support both encoding and decoding capabilities and may be implemented either in software as part of the vendor specific audio driver (VSAP) stack, or in hardware as part of the audio DSP or Bluetooth Controller. The diagram mentions LC3 by name since it's the standard codec supported by the Bluetooth SIG. However, future codecs and vendor specific codecs supported by Windows may also be incorporated into the architecture in a similar manner. + +### Architecture Variants + +The Bluetooth LE Audio VSAP architecture supports different variants for streaming. + +1. Sideband Bluetooth LE Audio streaming without audio offload +1. Sideband Bluetooth LE Audio streaming with audio offload +1. Vendor specific inband Bluetooth LE Audio streaming + +In the following diagrams, the shaded components are provided by the IHV and the nonshaded components are provided by the OS. + +#### Sideband Bluetooth LE Audio architecture without audio offload + +A sideband architecture uses a vendor specific audio interface to allow the audio driver stack to send and receive audio data to the Bluetooth controller. This data path is separate from the HCI data path used for other Bluetooth data, such as signaling messages between the unicast client and remote unicast server. The following diagram models a sideband architecture where the LC3 codec is hosted in the Bluetooth controller. It's also valid to have the LC3 codec hosted as part of the Vendor Specific Audio Driver Stack for software encoding and decoding. In that case, the audio being sent to the Bluetooth controller would be formatted as LC3 audio frames instead of PCM audio. + +The following diagram shows a sideband Bluetooth LE Audio architecture with an LC3 codec in the Bluetooth controller. + +:::image type="content" source="images/bluetooth-le-audio-architecture-with-lc3-codec-in-bluetooth-controller.png" alt-text="Diagram of sideband Bluetooth LE Audio architecture with LC3 codec in the Bluetooth controller."::: + +The following diagram shows a sideband Bluetooth LE Audio architecture with an LC3 codec in the audio driver stack. + +:::image type="content" source="images/bluetooth-le-audio-architecture-with-lc3-codec-in-audio-driver-stack.png" alt-text="Diagram of sideband Bluetooth LE Audio architecture with LC3 codec in the audio driver stack."::: + +#### Sideband Bluetooth LE Audio architecture with audio offload + +A sideband architecture with audio offload includes an audio DSP hardware component to provide a Bluetooth LE Audio streaming solution with power saving benefits. The following diagrams demonstrate a possible architecture with the LC3 codec in the Bluetooth controller and the codec in the audio DSP. + +The following diagram shows a sideband Bluetooth LE Audio with audio offload architecture with an LC3 codec in the Bluetooth controller. + +:::image type="content" source="images/bluetooth-le-audio-with-audio-offload-architecture-with-lc3-codec-in-bluetooth-controller.png" alt-text="Diagram of sideband Bluetooth LE Audio with audio offload architecture with LC3 codec in the Bluetooth controller."::: + +The following diagram shows a sideband Bluetooth LE Audio with audio offload architecture with an LC3 codec in the audio DSP. + +:::image type="content" source="images/bluetooth-le-audio-with-audio-offload-architecture-with-lc3-codec-in-audio-dsp.png" alt-text="Diagram of sideband Bluetooth LE Audio with audio offload architecture with LC3 codec in the audio DSP."::: + +#### Vendor specific inband Bluetooth LE Audio architecture + +The VSAP inband architecture enables a custom pipeline to send and receive Bluetooth LE Audio data from the vendor specific audio driver stack to the Bluetooth controller's HCI. This architecture includes a new component, the "IHV ISO Merging Component." This component is responsible for managing the flow control for the ISO data. It also shall share HCI command flow control with the Windows Bluetooth Core Stack if it needs to send any HCI commands. + +The following diagram shows a vendor specific inband Bluetooth LE Audio architecture. + +:::image type="content" source="images/bluetooth-le-audio-vendor-specific-inband-architecture.png" alt-text="Diagram of a vendor specific inband Bluetooth LE Audio architecture."::: + +## Detailed design + +### Audio format requirements + +#### Audio frame durations + +The Bluetooth LE Audio profiles allow implementations to support audio streaming with audio frame durations of either 7.5 milliseconds or 10 milliseconds. Windows requires the codecs provided by IHVs to support both frame durations to ensure interoperability with Bluetooth LE Audio accessory devices and quality coexistence with other Bluetooth LE devices connected to the system. + +#### Signal processing mode definitions + +Bluetooth LE Audio supports a wide range of streaming formats to support different user scenarios. The BAP and TMAP specifications define mandatory supported formats for certification. Windows applies [audio signal processing modes](../audio/audio-signal-processing-modes.md) to correlate the format to use with the scenario being performed by the system. Audio drivers that support Bluetooth LE Audio shall indicate support for the signal processing modes and formats in the following table. Furthermore, Bluetooth LE Audio doesn't support the raw signal processing mode, so audio drivers shall not advertise any supported formats for this mode. + +##### Render stream audio signal processing modes + +Bluetooth LE Audio requires render audio formats to be declared for the following signal processing modes: + +- Default (AUDIO_SIGNALPROCESSINGMODE_DEFAULT) + - This mode is used for unidirectional render scenarios, such as music playback, notifications, and video game audio. +- Communications (AUDIO_SIGNALPROCESSINGMODE_COMMUNICATIONS) + - This mode is used for bidirectional scenarios, such as voice calls. + +The following tables are lists of formats for each use case and signal processing mode. Audio formats are ordered from most preferred to least preferred. + +###### System sounds, music playback, and video game audio when connected to a stereo device or coordinated set of devices + +Signal processing mode: **Default** + +| Sampling Frequency | Channel Count | Bit Depth | Frame Duration | Audio Data Rate | BAP Codec Configuration ID (Table 3.11 of the BAP Specification) | +|---|---|---|---|---|---| +| 48 kHz | 2 | 16 | 7.5 ms | 96 kbps | 48_3 | +| 48 kHz | 2 | 16 | 7.5 ms | 80 kbps | 48_1 | +| 48 kHz | 2 | 16 | 10 ms | 96 kbps | 48_4 | +| 48 kHz | 2 | 16 | 10 ms | 80 kbps | 48_2 | +| 24 kHz | 2 | 16 | 7.5 ms | 48 kbps | 24_1 | +| 24 kHz | 2 | 16 | 10 ms | 48 kbps | 24_2 | + +###### System sounds, music playback, and video game audio when connected to a single member of a coordinated set (single earbud or hearing aid) + +Signal processing mode: **Default** + +| Sampling Frequency | Channel Count | Bit Depth | Frame Duration | Audio Data Rate | BAP Codec Configuration ID (Table 3.11 of the BAP Specification) | +|---|---|---|---|---|---| +| 48 kHz | 1 | 16 | 7.5 ms | 96 kbps | 48_3 | +| 48 kHz | 1 | 16 | 7.5 ms | 80 kbps | 48_1 | +| 48 kHz | 1 | 16 | 10 ms | 96 kbps | 48_4 | +| 48 kHz | 1 | 16 | 10 ms | 80 kbps | 48_2 | +| 24 kHz | 1 | 16 | 7.5 ms | 48 kbps | 24_1 | +| 24 kHz | 1 | 16 | 10 ms | 48 kbps | 24_2 | +| 16 kHz | 1 | 16 | 7.5 ms | 32 kbps | 16_1 | +| 16 kHz | 1 | 16 | 10 ms | 32 kbps | 16_2 | + +###### Render voice recorder, VOIP calls, or video game audio with voice chat + +Signal processing mode: **Communications** + +| Sampling Frequency | Channel Count | Bit Depth | Frame Duration | Audio Data Rate | BAP Codec Configuration ID (Table 3.11 of the BAP Specification) | +|---|---|---|---|---|---| +| 32 kHz | 1 | 16 | 7.5 ms | 64 kbps | 32_1 | +| 32 kHz | 1 | 16 | 10 ms | 64 kbps | 32_2 | +| 24 kHz | 1 | 16 | 7.5 ms | 48 kbps | 24_1 | +| 24 kHz | 1 | 16 | 10 ms | 48 kbps | 24_2 | +| 16 kHz | 1 | 16 | 7.5 ms | 32 kbps | 16_1 | +| 16 kHz | 1 | 16 | 10 ms | 32 kbps | 16_2 | + +##### Capture stream audio signal processing modes + +Bluetooth LE Audio requires capture audio formats to be declared for the Default (AUDIO_SIGNALPROCESSINGMODE_DEFAULT) signal processing mode. The list of supported capture formats is in the following table. + +Audio formats are ordered from most preferred to least preferred. + +###### Capture voice recorder, VOIP calls, or video game audio with voice chat + +Signal processing mode: **Default** + +| Sampling Frequency | Channel Count | Bit Depth | Frame Duration | Audio Data Rate | BAP Codec Configuration ID (Table 3.11 of the BAP Specification) | +|---|---|---|---|---|---| +| 32 kHz | 1 | 16 | 7.5 ms | 64 kbps | 32_1 | +| 32 kHz | 1 | 16 | 10 ms | 64 kbps | 32_2 | +| 24 kHz | 1 | 16 | 7.5 ms | 48 kbps | 24_1 | +| 24 kHz | 1 | 16 | 10 ms | 48 kbps | 24_2 | +| 16 kHz | 1 | 16 | 7.5 ms | 32 kbps | 16_1 | +| 16 kHz | 1 | 16 | 10 ms | 32 kbps | 16_2 | + +#### Defined stream configurations and topologies + +##### Render-only configurations + +###### Basic audio profile configuration 1 + +The following audio configuration is defined in table 4.1 of the [Bluetooth BAP specification](https://www.bluetooth.com/specifications/specs/basic-audio-profile-1-0-1/) + +:::image type="content" source="images/bap-configuration-1.png" alt-text="Diagram of basic audio profile configuration 1."::: + +The PC is connected to a single audio device that supports mono streams. The single device may be a standalone device or a single connected member of a coordinated set. + +| Use Case Examples | Windows Audio Settings | Bluetooth Controller Settings | +|---|---|---| +| Media playback | **Render**:
Signal Processing Mode: Default
Channel Count: 1
**Capture**: None | CIS Count: 1
CIG Count: 1
BAP QoS Settings: High reliability | +| Voice call with no microphone on audio device | **Render**:
Signal Processing Mode: Communications
Channel Count: 1
**Capture**: None | CIS Count: 1
CIG Count: 1
BAP QoS Settings: Low latency | +| Video game playback | **Render**:
Signal Processing Mode: Default
Channel Count: 1
**Capture**: None | CIS Count: 1
CIG Count: 1
BAP QoS Settings: Low latency | + +###### Basic audio profile configuration 4 + +The following audio configuration is defined in table 4.1 of the [Bluetooth BAP specification](https://www.bluetooth.com/specifications/specs/basic-audio-profile-1-0-1/) + +:::image type="content" source="images/bap-configuration-4.png" alt-text="Diagram of basic audio profile configuration 4."::: + +The PC is connected to a single audio device that supports stereo streams. The audio device is capable of processing two audio channels on a single CIS. + +| Use Case Examples | Windows Audio Settings | Bluetooth Controller Settings | +|---|---|---| +| Media playback | **Render**: Signal Processing Mode: Default
Channel Count: 2
**Capture**: None | CIS Count: 1
CIG Count: 1
BAP QoS Settings: High reliability Audio Channel Allocation: Front left and front right | +| Video game playback | Signal Processing Mode: Default
Channel Count: 2
**Capture**: None | CIS Count: 1
CIG Count: 1
BAP QoS Settings: Low latency
Audio Channel Allocation: Front left and front right | + +###### Basic audio profile configuration 6(i) + +The following audio configuration is defined in table 4.1 of the [Bluetooth BAP specification](https://www.bluetooth.com/specifications/specs/basic-audio-profile-1-0-1/) + +:::image type="content" source="images/bap-configuration-6-i.png" alt-text="Diagram of basic audio profile configuration 6 I."::: + +The PC is connected to a single audio device that supports stereo streams. The audio device is only capable of processing one audio channel on each of the two CISs + +| Use Case Examples | Windows Audio Settings | Bluetooth Controller Settings | +|---|---|---| +| Media playback | Signal Processing Mode: Default
Channel Count: 2
**Capture**: None | CIS Count: 2
CIG Count: 1
BAP QoS Settings: High reliability | +| Voice call with no microphone on audio device | Signal Processing Mode: Communications
Channel Count: 1
**Capture**: None | CIS Count: 2
CIG Count: 1
BAP QoS Settings: Low latency
Audio Channel Allocation: Either front left or front right | +| Video game playback | Signal Processing Mode: Default
Channel Count: 2
**Capture**: None | CIS Count: 2
CIG Count: 1
BAP QoS Settings: Low latency
Audio Channel Allocation: Front left and front right | + +###### Basic audio profile configuration 6(ii) + +The following audio configuration is defined in table 4.1 of the [Bluetooth BAP specification](https://www.bluetooth.com/specifications/specs/basic-audio-profile-1-0-1/) + +:::image type="content" source="images/bap-configuration-6-ii.png" alt-text="Diagram of basic audio profile configuration 6 II."::: + +The PC is connected to a coordinated set of audio devices. The set is capable of processing two channels of audio with each member processing a single channel. + +| Use Case Examples | Windows Audio Settings | Bluetooth Controller Settings | +|---|---|---| +| Media playback | Signal Processing Mode: Default
Channel Count: 2
**Capture**: None | CIS Count: 2
CIG Count: 1
BAP QoS Settings: High reliability | +| Voice call with no microphone on either device | Signal Processing Mode: Communications
Channel Count: 1
**Capture**: None | CIS Count: 2
CIG Count: 1
BAP QoS Settings: Low latency | +| Video game playback | Signal Processing Mode: Default
Channel Count: 2
**Capture**: None | CIS Count: 2
CIG Count: 1
BAP QoS Settings: Low latency | + +##### Bidirectional configurations + +Bidirectional configurations are used when the Bluetooth LE Audio profile detects that an application intends to create both a capture and render stream to a remote device or set of devices. Since applications control capture and render streams separately, IHV audio drivers and Bluetooth controllers shall allow audio to flow over a single direction of a bidirectional CIS after it's provisioned using the HCI commands Configure Data Path and LE Setup ISO Data Path. + +###### Basic audio profile configuration 3 + +The following audio configuration is defined in table 4.1 of the [Bluetooth BAP specification](https://www.bluetooth.com/specifications/specs/basic-audio-profile-1-0-1/) + +:::image type="content" source="images/bap-configuration-3.png" alt-text="Diagram of basic audio profile configuration 3."::: + +The PC is connected to a single audio device with a bidirectional mono stream established on a single CIS. + +| Use Case | Windows Audio Settings | Bluetooth Controller Settings | +|---|---|---| +| Voice call | **Render:**
Signal Processing Mode: Communications
Channel Count: 1
**Capture:**
Signal Processing Mode: Default
Channel Count: 1 | CIS Count: 1
CIG Count: 1
BAP QoS Settings: Low Latency | +| Video game playback with voice chat | **Render:**
Signal Processing Mode: Communications
Channel Count: 1
**Capture:**
Signal Processing Mode: Default
Channel Count: 1 | CIS Count: 1
CIG Count: 1
BAP QoS Settings: Low Latency | + +###### Basic audio profile configuration 8(i) + +The following audio configuration is defined in table 4.1 of the [Bluetooth BAP specification](https://www.bluetooth.com/specifications/specs/basic-audio-profile-1-0-1/) + +:::image type="content" source="images/bap-configuration-8-i.png" alt-text="Diagram of basic audio profile configuration 8 I."::: + +The PC is connected to a single audio device that supports stereo render streams and mono capture streams. The device is capable of processing one channel of audio on a single CIS for a given direction. + +| Use Case | Windows Audio Settings | Bluetooth Controller Settings | +|---|---|---| +| Voice call | **Render:**
Signal Processing Mode: Communications
Channel Count: 1
**Capture:**
Signal Processing Mode: Default
Channel Count: 1 | CIS Count: 2
CIG Count: 1
BAP QoS Settings: Low Latency | +| Video game playback with voice chat | **Render:**
Signal Processing Mode: Communications
Channel Count: 2
**Capture:**
Signal Processing Mode: Default
Channel Count: 1 | CIS Count: 2
CIG Count: 1
BAP QoS Settings: Low Latency | + +###### Basic audio profile configuration 8(ii) + +The following audio configuration is defined in table 4.1 of the [Bluetooth BAP specification](https://www.bluetooth.com/specifications/specs/basic-audio-profile-1-0-1/) + +:::image type="content" source="images/bap-configuration-8-ii.png" alt-text="Diagram of basic audio profile configuration 8 II."::: + +The PC is connected to a coordinated set of audio devices. Each set member is receiving one channel of render audio. A single set member has an established capture stream. The set member with the capture stream is the first set member that connects to the PC that also supports capture streams. + +| Use Case | Windows Audio Settings | Bluetooth Controller Settings | +|---|---|---| +| Voice call | **Render:**
Signal Processing Mode: Communications
Channel Count: 1
**Capture:**
Signal Processing Mode: Default
Channel Count: 1 | CIS Count: 2
CIG Count: 1
BAP QoS Settings: Low Latency | +| Video game playback with voice chat | **Render:**
Signal Processing Mode: Communications
Channel Count: 2
**Capture:**
Signal Processing Mode: Default
Channel Count: 1 | CIS Count: 2
CIG Count: 1
BAP QoS Settings: Low Latency | + +##### Capture-only configurations + +###### Basic audio profile configuration 2 + +The following audio configuration is defined in table 4.1 of the [Bluetooth BAP specification](https://www.bluetooth.com/specifications/specs/basic-audio-profile-1-0-1/) + +:::image type="content" source="images/bap-configuration-2.png" alt-text="Diagram of basic audio profile configuration 2."::: + +The PC is connected to a single audio device that supports mono capture streams. + +| Use Case | Windows Audio Settings | Bluetooth Controller Settings | +|---|---|---| +| Voice call with no speaker on device | Render: None
Capture:
Signal Processing Mode: Default
Channel Count: 1 | CIS Count: 1
CIG Count: 1
BAP QoS Settings: Low Latency | + +###### Basic audio profile configuration 9(i) + +The following audio configuration is defined in table 4.1 of the [Bluetooth BAP specification](https://www.bluetooth.com/specifications/specs/basic-audio-profile-1-0-1/) + +:::image type="content" source="images/bap-configuration-9-i.png" alt-text="Diagram of basic audio profile configuration 9 I."::: + +The PC is connected to a single audio device that supports sending stereo audio data. The device is capable of encoding one channel of audio on a single CIS. + +| Use Case | Windows Audio Settings | Bluetooth Controller Settings | +|---|---|---| +| Multi channel microphone capture | Render: None
Capture:
Signal Processing Mode: Default
Channel Count: 1
| CIS Count: 2
CIG Count: 1
BAP QoS Settings: Low Latency | + +###### Basic audio profile configuration 9(ii) + +The PC is connected to a single audio device that supports mono capture streams. + +The following audio configuration is defined in table 4.1 of the [Bluetooth BAP specification](https://www.bluetooth.com/specifications/specs/basic-audio-profile-1-0-1/) + +:::image type="content" source="images/bap-configuration-9-ii.png" alt-text="Diagram of basic audio profile configuration 9 II."::: + +The PC is connected to a set of audio devices. Each set member sends one channel of audio to the PC. + +| Use Case | Windows Audio Settings | Bluetooth Controller Settings | +|---|---|---| +| Multi channel microphone capture | Render: None
Capture:
Signal Processing Mode: Default
Channel Count: 1 | CIS Count: 2
CIG Count: 1
BAP QoS Settings: Low Latency | + +If the remote device or device set supports bidirectional audio, then the configurations for a capture only stream are the same as bidirectional configurations. This allows transitions from capture only scenarios to bidirectional scenarios without needing to re-create the streams. + +### Data structures + +#### Microsoft defined Bluetooth LE Audio interface properties + +##### Stream creation properties + +The following properties are shared between the vendor specific audio driver stack and the Bluetooth LE Audio Profile via the [ACXOBJECTBAG](/windows-hardware/drivers/audio/acx-summary-of-objects#acx-object-bag) [DDIs](/windows-hardware/drivers/ddi/acxmisc/) to inform decisions on stream endpoint creation and configuration, as shown in the [Stream Creation](#stream-creation) scenario. + +###### BluetoothLEAudio_CodecCapabilities + +This property is set by the audio driver to indicate support for audio streaming capabilities that are supported in the audio driver or audio DSP. The property value is set using the DDI **[AcxObjectBagAddBlob](/windows-hardware/drivers/ddi/acxmisc/nf-acxmisc-acxobjectbagaddblob)** and the format of the value is the same as a PAC record as defined in the [PACS specification](https://www.bluetooth.com/specifications/specs/published-audio-capabilities-service-1-0-1/). + +The Windows Bluetooth LE Audio profile reads the property to determine the possible codec configurations and stream composition to use. + +| Field | Octet | +|---|---| +| Capability Count | 0 | +| Codec ID[i] | 1-6 | +| Codec Specific Capabilities Length[i] | 7 | +| Codec Specific Capabilities | 8... n | +| Metadata Length (m) | n + 1 | +| Metadata | n+2... m | + +Field values are defined in tables 3.2 and 3.4 of the PACS specification. + +###### Bluetooth_DatapathID + +This property is set by the audio driver to indicate the data path ID used as the parameter for the commands HCI_LE_Setup_ISO_Data_Path and HCI_Configure_Data_Path. The property value is set using the **[AcxObjectBagAddUI8](/windows-hardware/drivers/ddi/acxmisc/nf-acxmisc-acxobjectbagaddui8)** DDI. + +The Bluetooth LE Audio profile reads and uses this property is as a parameter in HCI_Configure_Data_Path and HCI_LE_Setup_ISO_Data_Path commands. This ID is applied for all isochronous streams created for the **ACXSTREAM** associated with the object bag. + +| Field | Octet | +|---|---| +| Data path ID | 0 | + +If the property isn't set by the audio driver, then the OS uses the value 1 as the parameter for the HCI commands. + +###### Bluetooth_DatapathConfiguration + +This property is set by the audio driver to provide vendor specific configurations to the Bluetooth controller via the HCI_Configure_Data_Path command. It shall not be larger than 255 bytes, which is the largest payload that a Bluetooth controller accepts for an HCI command. The property value is set using the **[AcxObjectBagAddBlob](/windows-hardware/drivers/ddi/acxmisc/nf-acxmisc-acxobjectbagaddblob)** DDI. This configuration is applied for everything data path ID set by the audio driver. + +###### BluetoothLEAudio_CodecConfiguration + +This property shall be set by the Bluetooth LE Audio profile using the DDI **[AcxObjectBagAddBlob](/windows-hardware/drivers/ddi/acxmisc/nf-acxmisc-acxobjectbagaddblob)** after the codec configuration is configured with an audio device. The structure of the value is: + +| Field | Octet | +|---|---| +| Configuration Count | 0 | +| Coding Format[i] | 3 | +| Company ID[i] | 1-2 | +| Vendor Specific Codec ID[i] | 3-4 | +| Codec Specific Configuration Length[i] | 5 | +| Codec Specific Configuration[i] | 6... n | + +Field values are defined in table 4.3 of the [Bluetooth Audio Stream Control Service Specification](https://www.bluetooth.com/specifications/specs/audio-stream-control-service/). + +The vendor specific audio driver stack should read this property if the LC3 codec is in the ACX streaming driver or audio DSP. + +### Interfaces + +#### Audio endpoint template binding IDs + +Used by the audio driver's ACX circuit factory to know when an ACX circuit for a paired Bluetooth device is created. + +The following component IDs are used to create Bluetooth LE Audio circuits: + +```cpp +// {5C52FDB5-722A-4AB7-A342-70163B7E9B5C} +DEFINE_GUID(GUID_BLUETOOTH_LEAUDIO_RENDER_COMPONENT_ID, +0x5c52fdb5, 0x722a, 0x4ab7, 0xa3, 0x42, 0x70, 0x16, 0x3b, 0x7e, 0x9b, 0x5c); + +// {1DFF2EE3-AE89-441C-BDE3-24F885C55DF8} +DEFINE_GUID(GUID_BLUETOOTH_LEAUDIO_CAPTURE_COMPONENT_ID, +0x1dff2ee3, 0xae89, 0x441c, 0xbd, 0xe3, 0x24, 0xf8, 0x85, 0xc5, 0x5d, 0xf8); +``` + +#### Bluetooth LE Audio support interface + +Used by the audio driver stack to indicate that it's available for streaming Bluetooth LE Audio. Windows Bluetooth Audio service-level watch for this interface and wait until it's published before enabling Bluetooth LE Audio support. + +The following interface IDs are used to publish the Bluetooth LE Audio support interface: + +```cpp +// {BA02FA1B-0FD0-4A0F-A748-4FAE2E2D2F67} +DEFINE_GUID(GUID_BLUETOOTH_LEAUDIO_SUPPORT_INTERFACE, +0xba02fa1b, 0x0fd0, 0x4a0f, 0xa7, 0x48, 0x4f, 0xae, 0x2e, 0x2d, 0x2f, 0x67); +``` + +### Sequences + +#### Audio driver initialization + +When the IHV ACX Streaming driver loads and determines that it supports Bluetooth LE Audio streaming, it shall show support for the technology by creating an **ACXFACTORYCIRCUIT** object and registering for Bluetooth template bindings with ACX using the IDs defined in [Audio Endpoint Template Binding IDs](#audio-endpoint-template-binding-ids). + +:::image type="content" source="images/btle-audio-driver-init-seq.png" alt-text="Diagram of the Bluetooth LE Audio driver initialization sequence."::: + +#### Endpoint creation + +1. When an LE Audio device is paired with the system, the Bluetooth LE Audio Profile: + 1. Reads the published audio capabilities of the remote device. + 1. Discovers the controller supported capabilities by sending the commands HCI_Read_Local_Support_Codecs [v2] and HCI_Read_Local_Supported_Codec_Capabilities. + 1. Creates an [ACXCIRCUIT](/windows-hardware/drivers/audio/acx-summary-of-objects#acx-circuit) with the supported formats set based on the codec capabilities supported by the Bluetooth controller and remote audio device. If the controller doesn't support any codecs because codec support is in the audio DSP or audio driver, then the supported formats are set to the formats supported by the remote audio device. +1. After the **ACXCIRCUIT** is created, ACX requests the IHV ACX streaming driver's ACX circuit factory to create an **ACXCIRCUIT** for stream processing. +1. When a request to create a circuit is received, the IHV ACX streaming driver: + 1. Creates **ACXCIRCUIT**, [ACXPIN](/windows-hardware/drivers/audio/acx-summary-of-objects#acx-pin), [ACXOBJECTBAG](/windows-hardware/drivers/audio/acx-summary-of-objects#acx-object-bag), and [ACXSTREAMBRIDGE](/windows-hardware/drivers/audio/acx-summary-of-objects#acx-stream-bridge) objects. + 1. If the LC3 or vendor specific codec is hosted in the audio driver or DSP, then the IHV ACX streaming driver sets the *BluetoothLEAudio_CodecCapabilities* property on the **ACXOBJECTBAG**. + 1. The IHV ACX streaming driver may set *Bluetooth_DatapathID* or *Bluetooth_DatapathConfiguration* on the **ACXOBJECTBAG** if it's known at this time. +1. After both circuits are created, ACX invokes the **[EvtAcxPinConnected](/windows-hardware/drivers/ddi/acxpin/nc-acxpin-evt_acx_pin_connected)** callback on the IHV ACX driver's bridge pin. +1. When it's **EvtAcxPinConnected** callback is invoked, the IHV ACX streaming driver: + 1. Retrieves the bridge pin of the profile circuit with **[AcxTarget...](/windows-hardware/drivers/ddi/acxtargets/)** APIs to retrieve the formats supported by the profile circuit. + 1. Iterates through the list of **ACXDATAFORMAT**s set by the profile circuit. If the Bluetooth audio codec is hosted in the audio driver or audio DSP, then the IHV audio driver updates its **ACXDATAFORMAT**s with the formats that are supported by the codec and profile circuit. Otherwise, all formats are copied to the IHV ACX streaming driver's host pin. + 1. Sets the updated format list on the bridge pin if an audio-engine is created for offload streaming. +1. After the formats are updated, ACX enables both interfaces, and an audio endpoint is created. + +:::image type="content" source="images/btle-audio-endpoint-creation.png" alt-text="Diagram of the Bluetooth LE Audio endpoint creation."::: + +#### Stream creation + +1. When an application requests to create an audio stream, ACX invokes the registered **EvtCircuitCreateStream** callbacks for each circuit, beginning with the IHV ACX streaming driver. +1. When its **EvtCircuitCreateStream** callback is invoked, the IHV ACX streaming driver: + 1. Sets or updates the Bluetooth_DatapathId and Bluetooth_DataPathConfiguration properties on the [ACXOBJECTBAG](/windows-hardware/drivers/audio/acx-summary-of-objects#acx-object-bag) attached to the [ACXSTREAMBRIDGE](/windows-hardware/drivers/audio/acx-summary-of-objects#acx-stream-bridge). + 1. Creates an [ACXSTREAM](/windows-hardware/drivers/audio/acx-summary-of-objects#acx-stream) with callbacks set for stream state transitions and RT stream processing + 1. Creates an audio-engine element on the stream if the audio pipeline supports offload streaming. + 1. Adds the **ACXSTREAM** to its stream bridge. This invokes the Bluetooth LE Audio profile's **EvtCircuitCreateStream** callback. +1. When its **[EvtAcxCircuitCreateStream](/windows-hardware/drivers/ddi/acxcircuit/nc-acxcircuit-evt_acx_circuit_create_stream)** callback is invoked, the Bluetooth LE Audio profile: + 1. Saves the properties locally from the **ACXOBJECTBAG** set by the IHV ACX streaming driver for future stream transition callbacks. + 1. If the audio endpoint is for unicast streaming the Bluetooth LE Audio profile: + 1. Performs the Config Codec Operation as defined in the BAP specification. The parameters for the operation are derived from the **ACXDATAFORMAT** specified in the **EvtAcxCircuitCreateStream** callback and either the other stream parameters in the **ACXOBJECTBAG** or the codec capabilities supported by the Bluetooth Controller. + 1. Sets the *BluetoothLEAudio_CodecConfiguration* property on the **ACXOBJECTBAG** with the value used to configure the remote audio devices. +1. If the IHV ACX streaming driver needs to update its data path ID or data path configuration based on the object bag values set by the profile, then it may invoke the KSPROPERTY set operations to update the value stored by the profile circuit. + 1. Creates an **ACXSTREAM** with callbacks set for stream state transitions. + +:::image type="content" source="images/btle-audio-stream-creation.png" alt-text="Diagram of the Bluetooth LE Audio stream creation."::: + +#### Stream state transitions + +ACX decides the circuit order of stream state transitions based on the audio flow and whether the state is transitioning to a more active or less active state. + +- For Render streams going from a less-active state to a more-active state, the profile circuit receives the event first, followed by the streaming circuit. +- For Render streams going from a more-active state to a less-active state, the streaming circuit receives the event first, followed by the profile circuit.  +- For Capture streams going from a less-active state to a more-active state, the streaming circuit receives the event first, followed by the profile circuit.  +- For Capture streams going from a more-active state to a less-active state, the profile circuit with receive the event first, followed by the streaming circuit. + +#### Prepare stream + +When its **[EvtAcxStreamPrepareHardware](/windows-hardware/drivers/ddi/acxstreams/nc-acxstreams-evt_acx_stream_prepare_hardware)** callback is invoked, the Bluetooth LE Audio profile: + +1. Allocates resources for a unicast stream by: + 1. Configuring a CIG with the HCI_LE_Set_CIG_Parameters command. + 1. Sending the ASCS config QoS operation to synchronize settings with the remote device. + +:::image type="content" source="images/btle-audio-stream-preparation-profile-circuit.png" alt-text="Diagram of the Bluetooth LE Audio stream preparation of a profile circuit."::: + +When its **EvtAcxStreamPrepareHardware** callback is invoked, the IHV ACX streaming driver allocates the necessary streaming resources and initializes the audio pipeline to be in the acquired state. + +:::image type="content" source="images/btle-audio-stream-preparation-streaming-circuit.png" alt-text="Diagram of the Bluetooth LE Audio stream preparation of a streaming circuit"::: + +#### Start stream + +When its **[EvtAcxStreamRun](/windows-hardware/drivers/ddi/acxstreams/nc-acxstreams-evt_acx_stream_run)** callback is invoked, the Bluetooth LE Audio profile: + +1. Applies any data path configuration settings set by the ACX streaming driver in the stream creation procedure using the HCI_Configure_Data_Path command. +1. Begins the stream start procedure by: + 1. Performing the BAP unicast stream Enable procedure for a unicast stream: + 1. Sending the Enable operation to the remote endpoints. + 1. Creating CISes if they aren't already created using the HCI_LE_Create_CIS command. +1. If the data path isn't already configured, the Bluetooth LE Audio profile: + 1. Establishes the ISO data paths using the HCI_LE_Setup_ISO_Data_Path command + 1. If the IHV ACX streaming driver sets the *BluetoothLEAudio_CodecCapabilities* property, the value of the Codec_ID field in HCI_LE_Setup_ISO_Data_Path shall be set to transparent (0x3) as defined in the Bluetooth Assigned Numbers. Otherwise, the value shall be the same as the Codec ID used in the config codec operation in the stream creation procedure. +1. If the audio stream is a unicast capture stream, the Bluetooth LE Audio profile performs the BAP receiver start ready operation. + +:::image type="content" source="images/btle-audio-stream-start-profile-circuit.png" alt-text="Diagram of the Bluetooth LE Audio stream starting of a profile circuit."::: + +When its **EvtAcxStreamRun** callback is invoked, the IHV ACX streaming driver starts processing incoming audio data from either the Windows audio system (render) or the Bluetooth controller (capture). + +:::image type="content" source="images/btle-audio-stream-start-streaming-circuit.png" alt-text="Diagram of the Bluetooth LE Audio stream starting of a streaming circuit."::: + +#### Pause stream + +When its **[EvtAcxStreamPause](/windows-hardware/drivers/ddi/acxstreams/nc-acxstreams-evt_acx_stream_pause)** callback is invoked, the Bluetooth LE Audio profile: + +1. Performs the BAP unicast stream disable procedure. +1. Removes the ISO data path using the HCI_LE_Remove_ISO_Data_Path command. +1. Performs the ASCS receiver stop ready procedure if the audio stream is a unicast capture stream. + +:::image type="content" source="images/btle-audio-stream-pause-profile-circuit.png" alt-text="Diagram of the Bluetooth LE Audio stream pausing of a profile circuit."::: + +When its **EvtAcxStreamPause** callback is invoked, the IHV ACX streaming driver pauses its audio processing pipeline. + +:::image type="content" source="images/btle-audio-stream-pause-streaming-circuit.png" alt-text="Diagram of the Bluetooth LE Audio stream pausing of a streaming circuit."::: + +#### Release stream + +When its **[EvtAcxStreamReleaseHardware](/windows-hardware/drivers/ddi/acxstreams/nc-acxstreams-evt_acx_stream_release_hardware)** callback is invoked, the Bluetooth LE Audio Profile performs the BAP unicast stream release procedure by: + +1. Sending the ASCS Release operation to the remote Bluetooth LE Audio device +1. Disconnecting the CIS if it isn't used by another active stream. +1. Removing the CIG if all CISes are disconnected. + +:::image type="content" source="images/btle-audio-stream-release-profile-circuit.png" alt-text="Diagram of the Bluetooth LE Audio stream releasing of a profile circuit."::: + +When its **EvtAcxStreamReleaseHardware** callback is invoked, the IHV ACX streaming driver releases its audio pipeline resources. + +:::image type="content" source="images/btle-audio-stream-release-streaming-circuit.png" alt-text="Diagram of the Bluetooth LE Audio stream releasing of a streaming circuit."::: + +#### Endpoint disconnection + +The Windows Bluetooth LE Audio profile updates an endpoint's connection state if the remote unicast device doesn't have an LE-ACL connection to the PC or is reporting through its PACS available audio contexts that it isn't available for streaming. When the endpoint is disconnected, the Windows audio service invalidates any active streams to the endpoint. This results in the stream pause and release sequences to occur. + +#### Endpoint removal + +A Bluetooth LE Audio endpoint is removed from the system when either the profile circuit or streaming circuit is destroyed. The profile circuit may be removed when the remote unicast device's pairing is removed from Windows or the Bluetooth radio is disabled. + +1. When the Windows Bluetooth LE Audio profile removes its circuit, ACX disables its endpoint interfaces to signal to the Windows audio service that the endpoint should be removed. +1. When the interfaces are disabled, the Windows audio service invalidates any active streams to the Bluetooth LE Audio endpoint, this operation results in the stream pause and release callbacks to be invoked on the streaming circuit. +1. To complete endpoint removal, ACX invalidates the IHV ACX streaming driver's circuit, which results in the WDF invoking the circuit's cleanup callback. +1. When its cleanup callback is invoked, the IHV ACX streaming driver releases its circuit. + +:::image type="content" source="images/btle-audio-endpoint-removal.png" alt-text="Diagram of the Bluetooth LE Audio endpoint removal."::: + +### Volume and mute + +The IHV ACX streaming circuit should only include volume and mute elements if the streaming driver requires an audio-engine. When using an audio-engine, the configuration flags must be set as such: + +```cpp +ACX_AUDIOENGINE_CONFIG audioEngineCfg; +ACX_AUDIOENGINE_CONFIG_INIT(&audioEngineCfg); +… + +audioEngineCfg.Flags |= AcxAudioEngineConfigVolumeSecondary; // Use this control only if endpoint doesn't have one. + +audioEngineCfg.MuteElement = muteElement; + +audioEngineCfg.Flags |= AcxAudioEngineConfigMuteSecondary; // Use this control only if endpoint doesn't have one. + +audioEngineCfg.PeakMeterElement = peakmeterElement; + +audioEngineCfg.Flags |= AcxAudioEngineConfigPeakMeterSecondary; // Use this control only if endpoint doesn't have one. +``` + +This is required to allow Bluetooth LE Audio endpoints to use the Bluetooth SIG defined volume and microphone control profiles for volume and mute changes for unicast audio endpoints. + +If the remote Bluetooth LE Audio device doesn't support the volume or microphone control services, or the endpoint is created for broadcast audio, then the volume and mute elements in the audio-engine shall serve as a fallback to handle the change requests from the audio system. The Windows audio system handles changes to volume and mute. If there's no audio-engine and either remote device doesn't support the volume, or microphone services or the audio endpoint is for broadcast audio. + +### Bluetooth LE and classic audio coexistence + +Windows shall ensure that only classic audio or LE audio is active for a paired Bluetooth audio device that supports both technologies. If LE audio is active, then the sideband DDIs for A2DP and HFP for the remote device are disabled and the profile circuit is created for the LE audio endpoint. If classic audio is active, the sideband DDIs for A2DP and HFP for the remote device are enabled and the profile circuit isn't created for the LE audio endpoint. + +### Power management + +Bluetooth LE Audio doesn't have any power management requirements or flows outside of what is already defined by [WDF](../wdf/pnp-and-power-management-callback-sequences.md). + +## Related topics + +- [ACX audio class extensions](../audio/acx-audio-class-extensions-overview.md) +- [Bluetooth Basic Audio Profile specification](https://www.bluetooth.com/specifications/specs/basic-audio-profile-1-0-1/) +- [Bluetooth Core 5.3 specification](https://www.bluetooth.com/specifications/specs/core-specification-5-3/) +- [Bluetooth Published Audio Capabilities Service Specification](https://www.bluetooth.com/specifications/specs/published-audio-capabilities-service/) +- [Bluetooth Audio Stream Control Service Specification](https://www.bluetooth.com/specifications/specs/audio-stream-control-service/) +- [Bluetooth Assigned Numbers](https://www.bluetooth.com/specifications/assigned-numbers/) +- [Bluetooth HFP bypass guidelines for audio drivers](../audio/bluetooth-bypass-guidelines-for-audio-drivers.md) +- [Bluetooth HFP bypass audio streaming](../audio/bluetooth-hfp-bypass-audio-streaming.md) diff --git a/windows-driver-docs-pr/bluetooth/bluetooth-low-energy-functions.md b/windows-driver-docs-pr/bluetooth/bluetooth-low-energy-functions.md deleted file mode 100644 index df5d666dda..0000000000 --- a/windows-driver-docs-pr/bluetooth/bluetooth-low-energy-functions.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Bluetooth Low Energy Functions -description: List of Bluetooth Low Energy functions -ms.date: 04/20/2017 ---- - -# Bluetooth Low Energy functions - -This section contains reference pages for the following Bluetooth Low Energy functions - -[BluetoothGATTGetServices](/windows/win32/api/bluetoothleapis/nf-bluetoothleapis-bluetoothgattgetservices) - -[BluetoothGATTGetIncludedServices](/windows/win32/api/bluetoothleapis/nf-bluetoothleapis-bluetoothgattgetincludedservices) - -[BluetoothGATTGetCharacteristics](/windows/win32/api/bluetoothleapis/nf-bluetoothleapis-bluetoothgattgetcharacteristics) - -[BluetoothGATTGetDescriptors](/windows/win32/api/bluetoothleapis/nf-bluetoothleapis-bluetoothgattgetdescriptors) - -[BluetoothGATTGetCharacteristicValue](/windows/win32/api/bluetoothleapis/nf-bluetoothleapis-bluetoothgattgetcharacteristicvalue) - -[BluetoothGATTGetDescriptorValue](/windows/win32/api/bluetoothleapis/nf-bluetoothleapis-bluetoothgattgetdescriptorvalue) - -[BluetoothGATTBeginReliableWrite](/windows/win32/api/bluetoothleapis/nf-bluetoothleapis-bluetoothgattbeginreliablewrite) - -[BluetoothGATTSetCharacteristicValue](/windows/win32/api/bluetoothleapis/nf-bluetoothleapis-bluetoothgattsetcharacteristicvalue) - -[BluetoothGATTEndReliableWrite](/windows/win32/api/bluetoothleapis/nf-bluetoothleapis-bluetoothgattendreliablewrite) - -[BluetoothGATTAbortReliableWrite](/windows/win32/api/bluetoothleapis/nf-bluetoothleapis-bluetoothgattabortreliablewrite) - -[BluetoothGATTSetDescriptorValue](/windows/win32/api/bluetoothleapis/nf-bluetoothleapis-bluetoothgattgetdescriptorvalue) - -[BluetoothGATTRegisterEvent](/windows/win32/api/bluetoothleapis/nf-bluetoothleapis-bluetoothgattregisterevent) - -[BluetoothGATTUnregisterEvent](/windows/win32/api/bluetoothleapis/nf-bluetoothleapis-bluetoothgattunregisterevent) - -## See Also - -[Bluetooth Low Energy Overview](bluetooth-low-energy-overview.md) - -[Creating a L2CAP Client Connection to a Remote Device](creating-a-l2cap-client-connection-to-a-remote-device.md) diff --git a/windows-driver-docs-pr/bluetooth/bluetooth-low-energy-overview.md b/windows-driver-docs-pr/bluetooth/bluetooth-low-energy-overview.md index 521b6f8b62..e4a88193ab 100644 --- a/windows-driver-docs-pr/bluetooth/bluetooth-low-energy-overview.md +++ b/windows-driver-docs-pr/bluetooth/bluetooth-low-energy-overview.md @@ -1,25 +1,25 @@ --- -title: Bluetooth Low Energy Overview -description: This section provides an overview of Bluetooth Low Energy introduced in Windows 8 -ms.date: 04/20/2017 +title: Bluetooth Low Energy (LE) overview +description: This article provides an overview of Bluetooth Low Energy (LE) in Windows. +ms.date: 03/02/2023 --- -# Bluetooth Low Energy Overview +# Bluetooth Low Energy (LE) overview -Beginning with Windows 8, Bluetooth Low Energy introduces a new physical layer that shares the same frequency space as Bluetooth Basic Rate. Profiles that are developed on this technology are organized into the Generic Attribute Profile (or GATT). +Bluetooth LE introduces a new physical layer that shares the same frequency space as Bluetooth basic rate. Profiles that are developed on this technology are organized into the generic attribute profile (GATT). Each profile defines the use of one or more services to create a use case or scenario. Compliant service implementations are constructed from characteristics organized in a way that conforms to the established schema defined on the Bluetooth Special Interest Group [developer website](https://www.bluetooth.com/specifications/gatt/services/). -The diagram below illustrates the way objects are structured inside a typical GATT service. +The following diagram illustrates the way objects are structured inside a typical GATT service. -![bluetooth low energy gatt service declarations.](images/bthleservicedeclaration.png) +:::image type="content" source="images/bthleservicedeclaration.png" alt-text="Diagram of Bluetooth LE GATT service declarations."::: -When a Bluetooth Low Energy device is paired with a Windows 8 machine, the device becomes part of the system and Windows will provide device objects to represent both the device and the primary services reported by the device. +When a Bluetooth LE device is paired with a Windows machine, the device becomes part of the system. Windows provides device objects to represent both the device and the primary services reported by the device. -![device object structure of the windows 8 bluetooth low energy implementation.](images/bthlewin8supt.png) +:::image type="content" source="images/bthlewin8supt.png" alt-text="Diagram of the device object structure of the Windows Bluetooth LE implementation."::: -Each device and its primary services are represented as device objects in Windows and these device objects can be queried and managed using the [device installation functions](/previous-versions/ff549791(v=vs.85)) such as [**SetupDiEnumDeviceInfo**](/windows/win32/api/setupapi/nf-setupapi-setupdienumdeviceinfo), and [**SetupDiGetDeviceProperty**](/windows/win32/api/setupapi/nf-setupapi-setupdigetdevicepropertyw). +Each device and its primary services are represented as device objects in Windows and these device objects can be queried and managed using the [device installation functions](../install/using-device-installation-functions.md) such as **[SetupDiEnumDeviceInfo](/windows/win32/api/setupapi/nf-setupapi-setupdienumdeviceinfo)**, and **[SetupDiGetDeviceProperty](/windows/win32/api/setupapi/nf-setupapi-setupdigetdevicepropertyw)**. -In addition to the standard [Bluetooth Profile Driver functions](bluetooth-profile-driver-functions.md), Windows 8 introduces new [Bluetooth Low Energy functions](bluetooth-low-energy-functions.md) which allows for the development of Bluetooth GATT client applications. +In addition to standard [Bluetooth profile driver functions](/windows-hardware/drivers/ddi/_bltooth/), [Bluetooth LE functions](/windows/win32/api/_bltooth/) provide functionality for the development of Bluetooth GATT client applications. -These functions allows for the enumeration of services and their objects (including services, characteristics and their descriptors) as well as read and write capabilities. +These functions allow for the enumeration of services and their objects (including services, characteristics and their descriptors) as well as read and write capabilities. \ No newline at end of file diff --git a/windows-driver-docs-pr/bluetooth/bluetooth-profile-driver-functions.md b/windows-driver-docs-pr/bluetooth/bluetooth-profile-driver-functions.md deleted file mode 100644 index f5c834e33c..0000000000 --- a/windows-driver-docs-pr/bluetooth/bluetooth-profile-driver-functions.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: Bluetooth Profile Driver Functions -description: List of Bluetooth functions supported with Profile drivers -ms.date: 04/20/2017 ---- - -# Bluetooth Profile Driver Functions - -This section contains reference pages for the following Bluetooth functions that are supported by the Bluetooth driver stack. - -[BluetoothSetLocalServiceInfo](/windows/win32/api/bluetoothapis/nf-bluetoothapis-bluetoothsetlocalserviceinfo) - -[BthAllocateBrb](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnbth_allocate_brb) - -[BthFreeBrb](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnbth_free_brb) - -[BthInitializeBrb](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnbth_initialize_brb) - -[BthReuseBrb](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnbth_reuse_brb) - -[IsBluetoothVersionAvailable](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnbth_is_bluetooth_version_available) - -[SdpAddAttributeToTree](/windows-hardware/drivers/ddi/sdplib/nf-sdplib-sdpaddattributetotree) - -[SdpAppendNodeToContainerNode](/windows-hardware/drivers/ddi/sdplib/nf-sdplib-sdpappendnodetocontainernode) - -[SdpByteSwapUint64](/windows-hardware/drivers/ddi/bthsdpddi/nc-bthsdpddi-pbyteswapuint64) - -[SdpByteSwapUint128](/windows-hardware/drivers/ddi/bthsdpddi/nc-bthsdpddi-pbyteswapuint128) - -[SdpByteSwapUuid128](/windows-hardware/drivers/ddi/bthsdpddi/nc-bthsdpddi-pbyteswapuuid128) - -[SdpConvertStreamToTree](/windows-hardware/drivers/ddi/bthsdpddi/nc-bthsdpddi-pconvertstreamtotree) - -[SdpCreateNodeAlternative](/windows-hardware/drivers/ddi/sdplib/nf-sdplib-sdpcreatenodealternative) - -[SdpCreateNodeBoolean](/windows-hardware/drivers/ddi/sdplib/nf-sdplib-sdpcreatenodeboolean) - -[SdpCreateNodeInt8](/windows-hardware/drivers/ddi/sdplib/nf-sdplib-sdpcreatenodeint8) - -[SdpCreateNodeInt16](/windows-hardware/drivers/ddi/sdplib/nf-sdplib-sdpcreatenodeint16) - -[SdpCreateNodeInt32](/windows-hardware/drivers/ddi/sdplib/nf-sdplib-sdpcreatenodeint32) - -[SdpCreateNodeInt64](/windows-hardware/drivers/ddi/sdplib/nf-sdplib-sdpcreatenodeint64) - -[SdpCreateNodeInt128](/windows-hardware/drivers/ddi/sdplib/nf-sdplib-sdpcreatenodeint128) - -[SdpCreateNodeNil](/windows-hardware/drivers/ddi/sdplib/nf-sdplib-sdpcreatenodenil) - -[SdpCreateNodeSequence](/windows-hardware/drivers/ddi/sdplib/nf-sdplib-sdpcreatenodesequence) - -[SdpCreateNodeString](/windows-hardware/drivers/ddi/sdplib/nf-sdplib-sdpcreatenodestring) - -[SdpCreateNodeTree](/windows-hardware/drivers/ddi/sdplib/nf-sdplib-sdpcreatenodetree) - -[SdpCreateNodeUInt8](/windows-hardware/drivers/ddi/sdplib/nf-sdplib-sdpcreatenodeuint8) - -[SdpCreateNodeUInt16](/windows-hardware/drivers/ddi/sdplib/nf-sdplib-sdpcreatenodeuint16) - -[SdpCreateNodeUInt32](/windows-hardware/drivers/ddi/sdplib/nf-sdplib-sdpcreatenodeuint32) - -[SdpCreateNodeUInt64](/windows-hardware/drivers/ddi/sdplib/nf-sdplib-sdpcreatenodeuint64) - -[SdpCreateNodeUInt128](/windows-hardware/drivers/ddi/sdplib/nf-sdplib-sdpcreatenodeuint128) - -[SdpCreateNodeUrl](/windows-hardware/drivers/ddi/sdplib/nf-sdplib-sdpcreatenodeurl) - -[SdpCreateNodeUUID16](/windows-hardware/drivers/ddi/sdplib/nf-sdplib-sdpcreatenodeuuid16) - -[SdpCreateNodeUUID32](/windows-hardware/drivers/ddi/sdplib/nf-sdplib-sdpcreatenodeuuid32) - -[SdpCreateNodeUUID128](/windows-hardware/drivers/ddi/sdplib/nf-sdplib-sdpcreatenodeuuid128) - -[SdpFindAttributeInTree](/windows-hardware/drivers/ddi/sdplib/nf-sdplib-sdpfindattributeintree) - -[SdpFreeTree](/windows-hardware/drivers/ddi/sdplib/nf-sdplib-sdpfreetree) - -[SdpGetNextElement](/windows-hardware/drivers/ddi/bthsdpddi/nc-bthsdpddi-pgetnextelement) - -[SdpRetrieveUint64](/windows-hardware/drivers/ddi/bthsdpddi/nc-bthsdpddi-pretrieveuint64) - -[SdpRetrieveUuid128](/windows-hardware/drivers/ddi/bthsdpddi/nc-bthsdpddi-pretrieveuuid128) - -[SdpValidateStream](/windows-hardware/drivers/ddi/bthsdpddi/nc-bthsdpddi-pvalidatestream) - -## See Also - -[L2CAP Client Connection](creating-a-l2cap-client-connection-to-a-remote-device.md) - -[SCO Client Connections](creating-a-sco-client-connection-to-a-remote-device.md) diff --git a/windows-driver-docs-pr/bluetooth/bluetooth-profile-drivers-overview.md b/windows-driver-docs-pr/bluetooth/bluetooth-profile-drivers-overview.md index cd31339e85..98da1bc228 100644 --- a/windows-driver-docs-pr/bluetooth/bluetooth-profile-drivers-overview.md +++ b/windows-driver-docs-pr/bluetooth/bluetooth-profile-drivers-overview.md @@ -1,15 +1,14 @@ --- -title: Introduction to Bluetooth Profile Drivers -description: Introduction to Bluetooth Profile Drivers +title: Introduction to Bluetooth profile drivers +description: Introduction to Bluetooth profile drivers keywords: - Bluetooth WDK , about Bluetooth - remote connections WDK Bluetooth - connections WDK Bluetooth -ms.date: 07/01/2019 +ms.date: 10/06/2022 --- -# Introduction to Bluetooth Profile Drivers - +# Introduction to Bluetooth profile drivers This section describes the support that Microsoft provides for the wireless Bluetooth protocol. Bluetooth is an industry standard protocol that enables wireless connectivity for a variety of devices including computers, mobile phones, handheld devices, mouse devices, keyboards, and printers. This section also provides guidelines on how to develop Bluetooth profile drivers for your Bluetooth-enabled device. Details of the Bluetooth protocol are available on the [Bluetooth](https://go.microsoft.com/fwlink/p/?linkid=26268) website. @@ -17,19 +16,19 @@ Microsoft provides support for the Bluetooth protocol in Microsoft Windows XP wi To support the Bluetooth protocol, Microsoft supplies several drivers and support files, including: -- *BthPort.sys* +- *BthPort.sys* -- *BthEnum.sys* +- *BthEnum.sys* -- *BthUsb.sys* +- *BthUsb.sys* -- *BthProps.cpl* +- *BthProps.cpl* IHVs must use Windows Vista or later to develop their profile drivers because earlier versions of Windows, including Windows XP with SP2, do not support profile driver development. The Bluetooth driver stack provides device driver interfaces (DDIs) that enable profile drivers to access Synchronous Connection-Oriented (SCO) links and Logical Link Controller and Adaptation Protocol (L2CAP) links between the local system and remote Bluetooth devices. -### **SCO** +## SCO Synchronous connection-oriented (SCO) links are point-to-point connections between two Bluetooth devices. They are defined primarily to support time-bounded information like voice. @@ -37,7 +36,7 @@ The Windows Vista Bluetooth driver stack has been enhanced to provide SCO kernel For more information about SCO, see [Creating a SCO Client Connection to a Remote Device](creating-a-sco-client-connection-to-a-remote-device.md) and [Accepting SCO Connections in a Bluetooth Profile Driver](accepting-sco-connections-in-a-bluetooth-profile-driver.md). -### **L2CAP and SDP** +## L2CAP and SDP The L2CAP is designed to support asynchronous connectionless link (ACL) Bluetooth links. The Bluetooth driver stack provides support for connection-oriented services. Profile drivers use the Bluetooth L2CAP DDIs to open, update, and close L2CAP connections, as well as to perform read and write operations over an open L2CAP connection. @@ -48,12 +47,3 @@ SDP records are advertised in a complex byte stream. Profile drivers can use the For more information about L2CAP and SDP, see [Creating a L2CAP Client Connection to a Remote Device](creating-a-l2cap-client-connection-to-a-remote-device.md), [Accepting L2CAP Connections in a Bluetooth Profile Driver](accepting-l2cap-connections-in-a-bluetooth-profile-driver.md) and [Communicating with SDP Servers](communicating-with-sdp-servers.md). For more information about the Bluetooth driver stack, see [Bluetooth Driver Stack](bluetooth-driver-stack.md). - - - - - - - - - diff --git a/windows-driver-docs-pr/bluetooth/bluetooth-proximity-profile.md b/windows-driver-docs-pr/bluetooth/bluetooth-proximity-profile.md index bed46f125f..2cb9833e05 100644 --- a/windows-driver-docs-pr/bluetooth/bluetooth-proximity-profile.md +++ b/windows-driver-docs-pr/bluetooth/bluetooth-proximity-profile.md @@ -1,82 +1,55 @@ --- title: Bluetooth Proximity Profile description: The Proximity Profile defines two roles intended to allow devices to detect their proximity. -ms.date: 04/20/2017 +ms.date: 10/06/2022 --- # Bluetooth Proximity Profile - The Proximity Profile defines two roles intended to allow devices to detect their proximity. The two roles are called: -- The Proximity Reporter -- The Proximity Monitor - -![role relationship.](images/bthleproximityroles.png) +- The Proximity Reporter +- The Proximity Monitor -## Proximity Reporter +:::image type="content" source="images/bthleproximityroles.png" alt-text="Diagram showing the role relationship between the Proximity Reporter and Proximity Monitor roles."::: +## Proximity Reporter -The Proximity Reporter is required to be a GATT server. +The Proximity Reporter is required to be a Generic ATTribute (GATT) server. The Proximity Reporter supports the following GATT services: -- Link Loss Service (mandatory) -- Immediate Alert Service (optional) -- Tx Power Service (optional) - -## Proximity Monitor - +- Link Loss Service (mandatory) +- Immediate Alert Service (optional) +- Tx Power Service (optional) -The Proximity Monitor is the GATT client. It should create and maintain a connection to the proximity Reporter as well as monitor the Radio Signal Strength Information (or RSSI) of the connection to calculate the signal’s path loss. If the optional "Tx Power Service" is available on the Proximity Reporter, it can also use this additional information to normalize the RSSI value by subtracting the RSSI from the Tx Power Level. +## Proximity Monitor -## Support for GATT in Windows 8.1 +The Proximity Monitor is the GATT client. It should create and maintain a connection to the proximity Reporter as well as monitor the Radio Signal Strength Information (or RSSI) of the connection to calculate the signal's path loss. If the optional Tx Power Service is available on the Proximity Reporter, it can also use this additional information to normalize the RSSI value by subtracting the RSSI from the Tx Power Level. +## Support for GATT in Windows -When a GATT device is paired with Windows 8.1, the device becomes part of the system and Windows will provide *device objects* to represent both the device and the primary services reported by the device. +When a GATT device is paired with Windows, the device becomes part of the system and Windows will provide *device objects* to represent both the device and the primary services reported by the device. -The [**Windows.Devices.Bluetooth.GenericAttributeProfile namespace**](/uwp/api/Windows.Devices.Bluetooth.GenericAttributeProfile). describes the Generic Attribute Profile APIs app developers can use in Windows 8.1. +The [**Windows.Devices.Bluetooth.GenericAttributeProfile namespace**](/uwp/api/Windows.Devices.Bluetooth.GenericAttributeProfile) describes the Generic Attribute Profile APIs app developers can use in Windows. -One of the first steps when developing a device app is to identify which Bluetooth services the app needs in order to accomplish the scenarios a user cares about. For the Proximity Profile, the device app needs to use the "Link Loss Service" and optionally the "Immediate Alert Service" and "Tx Power Service". +One of the first steps when developing a device app is to identify which Bluetooth services the app needs in order to accomplish the scenarios a user cares about. For the Proximity Profile, the device app needs to use the Link Loss Service and optionally the Immediate Alert Service and Tx Power Service. -In order for the device app to determine if any devices paired with Windows implement the "Link Loss Service" the app should use the APIs available in the [**Windows.Devices.Enumeration namespace**](/uwp/api/Windows.Devices.Enumeration), namely the DeviceInformation.FindAllAsync method. +In order for the device app to determine if any devices paired with Windows implement the Link Loss Service the app should use the APIs available in the [**Windows.Devices.Enumeration namespace**](/uwp/api/Windows.Devices.Enumeration), namely the DeviceInformation.FindAllAsync method. -The [**DeviceInformation.FindAllAsync method**](/uwp/api/Windows.Devices.Enumeration.DeviceInformation#Windows_Devices_Enumeration_DeviceInformation_FindAllAsync_System_String_) takes an *AQS (Advanced Query Syntax)* device selector as a parameter in order to filter only devices which contain the "Link Loss Service". Device app developers can also use the [**GetDeviceSelectorFromUuid**](/uwp/api/Windows.Devices.Bluetooth.GenericAttributeProfile.GattDeviceService#Windows_Devices_Bluetooth_GenericAttributeProfile_GattDeviceService_GetDeviceSelectorFromUuid_System_Guid_) or [**GetDeviceSelectorFromShortId**](/uwp/api/Windows.Devices.Bluetooth.GenericAttributeProfile.GattDeviceService#Windows_Devices_Bluetooth_GenericAttributeProfile_GattDeviceService_GetDeviceSelectorFromShortId_System_UInt16_) methods of the [**GattDeviceService**](/uwp/api/Windows.Devices.Bluetooth.GenericAttributeProfile.GattDeviceService) class, so they don’t need to manually construct the AQS filter. +The [**DeviceInformation.FindAllAsync method**](/uwp/api/Windows.Devices.Enumeration.DeviceInformation#Windows_Devices_Enumeration_DeviceInformation_FindAllAsync_System_String_) takes an *AQS (Advanced Query Syntax)* device selector as a parameter in order to filter only devices which contain the Link Loss Service. Device app developers can also use the [**GetDeviceSelectorFromUuid**](/uwp/api/Windows.Devices.Bluetooth.GenericAttributeProfile.GattDeviceService#Windows_Devices_Bluetooth_GenericAttributeProfile_GattDeviceService_GetDeviceSelectorFromUuid_System_Guid_) or [**GetDeviceSelectorFromShortId**](/uwp/api/Windows.Devices.Bluetooth.GenericAttributeProfile.GattDeviceService#Windows_Devices_Bluetooth_GenericAttributeProfile_GattDeviceService_GetDeviceSelectorFromShortId_System_UInt16_) methods of the [**GattDeviceService**](/uwp/api/Windows.Devices.Bluetooth.GenericAttributeProfile.GattDeviceService) class, so they don't need to manually construct the AQS filter. -The "Link Loss Service" is a Bluetooth GATT service defined by the Bluetooth SIG, and as such a *Short Id* can be used instead of a *fully-qualified UUID*. +The Link Loss Service is a Bluetooth GATT service defined by the Bluetooth SIG, and as such a *Short Id* can be used instead of a *fully-qualified UUID*. The *Short Id* service IDs assigned for a Proximity profile service are: - ---- - - - - - - - - - - - - - - - - - - - - -
Service NameShort Id

Link Loss

0x1803

Immediate Alert

0x1802

Tx Power

0x1804

- - +| Service Name | Short Id | +|--|--| +| Link Loss | 0x1803 | +| Immediate Alert | 0x1802 | +| Tx Power | 0x1804 | The Bluetooth SIG maintains the most up to date [list of services](https://go.microsoft.com/fwlink/p/?linkid=320723). @@ -88,16 +61,13 @@ These APIs enable access to specific services and their objects (for example Inc The [Bluetooth Generic Attribute Profile - Heart Rate Service](/samples/browse/) sample demonstrates some of these techniques. -## Using Power Efficiently +## Using Power Efficiently - -Support for Bluetooth Low Energy in Windows 8.1 has a strong focus on using power efficiently. This includes reducing the power consumption for the local Bluetooth radio adapter as well as using the CPU to be as little as possible. +Support for Bluetooth Low Energy in Windows has a strong focus on using power efficiently. This includes reducing the power consumption for the local Bluetooth radio adapter as well as using the CPU to be as little as possible. Therefore, to establish a Bluetooth LE connection an app needs to register a handler for the [**GattCharacteristic.ValueChanged**](/uwp/api/Windows.Devices.Bluetooth.GenericAttributeProfile.GattCharacteristic#Windows_Devices_Bluetooth_GenericAttributeProfile_GattCharacteristic_ValueChanged) event. Alternately, the app must call any of the [**GattCharacteristic.ReadValueAsync**](/uwp/api/Windows.Devices.Bluetooth.GenericAttributeProfile.GattCharacteristic#Windows_Devices_Bluetooth_GenericAttributeProfile_GattCharacteristic_ReadValueAsync_Windows_Devices_Bluetooth_BluetoothCacheMode_), [**GattCharacteristic.WriteValueAsync**](/uwp/api/Windows.Devices.Bluetooth.GenericAttributeProfile.GattCharacteristic#Windows_Devices_Bluetooth_GenericAttributeProfile_GattCharacteristic_WriteValueAsync_Windows_Storage_Streams_IBuffer_) or [**GattCharacteristic.WriteClientCharacteristicConfigurationDescriptorAsync**](/uwp/api/Windows.Devices.Bluetooth.GenericAttributeProfile.GattCharacteristic#Windows_Devices_Bluetooth_GenericAttributeProfile_GattCharacteristic_WriteClientCharacteristicConfigurationDescriptorAsync_Windows_Devices_Bluetooth_GenericAttributeProfile_GattClientCharacteristicConfigurationDescriptorValue_) methods without specifying the BluetoothCacheMode.Cached option. -**Note**  In order to minimize power consumption, Windows does not actively monitor the RSSI value of the link by polling the local Bluetooth radio controller. - - +> [!NOTE] +> In order to minimize power consumption, Windows does not actively monitor the RSSI value of the link by polling the local Bluetooth radio controller. Power considerations are described in [Proximity Profile Implementation Details](proximity-profile-implementation-details.md). - diff --git a/windows-driver-docs-pr/bluetooth/bluetooth-radio-error-recovery.md b/windows-driver-docs-pr/bluetooth/bluetooth-radio-error-recovery.md index 0f73ba4203..d7eda8da63 100644 --- a/windows-driver-docs-pr/bluetooth/bluetooth-radio-error-recovery.md +++ b/windows-driver-docs-pr/bluetooth/bluetooth-radio-error-recovery.md @@ -2,7 +2,7 @@ title: Bluetooth Radio Reset and Recovery description: Bluetooth radio automated error recovery mechanisms keywords: ["Bluetooth Radio Error Recovery", "Bluetooth PLDR"] -ms.date: 09/18/2019 +ms.date: 10/06/2022 --- # Bluetooth Radio Reset and Recovery @@ -37,23 +37,23 @@ While there are different approaches to recover from a failed state, Bluetooth u - The actual reset mechanism is system-specific. | Reset Level | Implementation | -| --- | --- | -| Function-level device reset (FLDR) | The reset operation is restricted to a specific device and is not visible to other devices. There is no re-enumeration. Function drivers must assume that the hardware has returned to its original state after the operation. Intermediary state is not preserved. -| Platform-level device reset (PLDR) | The reset operation affects a specific device and all other devices that are connected to it via the same power rail or reset line. The reset operation causes the device to be reported as missing from the bus and re-enumerated. This type of reset has the most impact on the system since all devices that share the resource go back to their original state.| +|--|--| +| Function-level device reset (FLDR) | The reset operation is restricted to a specific device and is not visible to other devices. There is no re-enumeration. Function drivers must assume that the hardware has returned to its original state after the operation. Intermediary state is not preserved. | +| Platform-level device reset (PLDR) | The reset operation affects a specific device and all other devices that are connected to it via the same power rail or reset line. The reset operation causes the device to be reported as missing from the bus and re-enumerated. This type of reset has the most impact on the system since all devices that share the resource go back to their original state. | -- **To support FLDR** there must be an __RST method defined within the __ADR_ namespace as detailed in [ACPI firmware: Function-level reset](../kernel/working-with-guid-device-reset-interface-standard.md#acpi-firmware-function-level-reset). +- **To support FLDR** there must be an __RST method defined inside the device scope as detailed in [ACPI firmware: Function-level reset](../kernel/working-with-guid-device-reset-interface-standard.md#acpi-firmware-function-level-reset). -- **To support PLDR** there must be an _RST or _PR3 method defined within the __ADR_ namespace as detailed in [ACPI firmware: Platform-level reset](../kernel/working-with-guid-device-reset-interface-standard.md#acpi-firmware-platform-level-reset). Note that if a __PR3_ method is used, ACPI uses the D3Cold power cycle mechanism to reset. This emulates removing power from the device and subsequently restoring it. If any other devices share the same power rail they will also be reset. If an __RST_ method is defined and referenced by a __PRR_ (PowerResource) then all devices that use that PowerResource will be affected. +- **To support PLDR** there must be an __RST or __PR3 method defined under the device scope as detailed in [ACPI firmware: Platform-level reset](../kernel/working-with-guid-device-reset-interface-standard.md#acpi-firmware-platform-level-reset). If a __PR3_ method is used, ACPI uses the D3Cold power cycle mechanism to reset. This emulates removing power from the device and subsequently restoring it. If any other devices share the same power rail they will also be reset. If an __RST_ method is defined and referenced by a __PRR_ (PowerResource) then all devices that use that PowerResource will be affected. - Since PLDR works only for internal devices, it must be declared as such in ACPI. For USB devices, to specify a port that is internal (not user visible) and can be connected to an integrated device, set the __UPC.PortIsConnectable_ byte to 0xFF and the __PLD.UserVisible_ bit to 0. - If the __PR3_ (D3Cold) mechanism is used for PLDR, ensure that scenarios like SystemWake and DeviceWake continue to work. Nominally, this means that there are appropriate power resources defined for D2, e.g. __PR2_. The following table is a useful guide: -| Power state | ACPI resource | Behavior | -| --- | --- | --- | -| D2 | _PR2 | Any power or clocks required for the class-defined reduced-functionality of this state. | -| D3 Hot (reqd.) | _PR2 | The same resources as the next higher state that is supported (D2, D1, or D0). | -| D3cold | _PR3 | Only the power or clocks required for the device to appear on its bus and respond to a bus-specific command.| +| Power state | ACPI resource | Behavior | +|--|--|--| +| D2 | _PR2 | Any power or clocks required for the class-defined reduced-functionality of this state. | +| D3 Hot (reqd.) | _PR2 | The same resources as the next higher state that is supported (D2, D1, or D0). | +| D3cold | _PR3 | Only the power or clocks required for the device to appear on its bus and respond to a bus-specific command. | ### Related links diff --git a/windows-driver-docs-pr/bluetooth/bluetooth-support-in-previous-windows-versions.md b/windows-driver-docs-pr/bluetooth/bluetooth-support-in-previous-windows-versions.md index 9af2bb3f96..f68bc5b42a 100644 --- a/windows-driver-docs-pr/bluetooth/bluetooth-support-in-previous-windows-versions.md +++ b/windows-driver-docs-pr/bluetooth/bluetooth-support-in-previous-windows-versions.md @@ -9,9 +9,6 @@ ms.date: 03/08/2022 > [!NOTE] > Looking for drivers for your Bluetooth audio device? See [Fix connections to Bluetooth audio devices and wireless displays](https://go.microsoft.com/fwlink/p/?LinkID=623629). -> [!NOTE] -> For information about Bluetooth support in Windows 11, see [Bluetooth Support in Windows 11](general-bluetooth-support-in-windows.md). - ## Which previous versions of Windows support Bluetooth wireless technology? The following previous versions of Windows include in-box support for Bluetooth wireless technology: @@ -21,10 +18,9 @@ The following previous versions of Windows include in-box support for Bluetooth The following previous versions of Windows **do not** have in-box support for Bluetooth wireless technology: -- All SKUs of Windows Server 2016 -- All SKUs of Windows Server 2012 R2 +- All SKUs of Windows Server -Although these versions of Windows do not have in-box Bluetooth wireless technology support, third-party Bluetooth drivers might be available from independent hardware vendors (IHVs). +Although Windows Server does not have in-box Bluetooth wireless technology support, third-party Bluetooth drivers might be available from independent hardware vendors (IHVs). ## Which Bluetooth versions do previous versions of Windows support? diff --git a/windows-driver-docs-pr/bluetooth/bluetooth-user-interface.md b/windows-driver-docs-pr/bluetooth/bluetooth-user-interface.md index 83e50f0438..4ef524d39e 100644 --- a/windows-driver-docs-pr/bluetooth/bluetooth-user-interface.md +++ b/windows-driver-docs-pr/bluetooth/bluetooth-user-interface.md @@ -1,73 +1,62 @@ --- title: Bluetooth user interface description: Describes working with the Bluetooth user interface in Windows for software developers and vendors -ms.date: 04/20/2017 +ms.date: 10/06/2022 --- -# Bluetooth User Interface +# Bluetooth user interface +This article describes working with the Bluetooth user interface in Windows for software developers and vendors. -## What is the Bluetooth File Transfer Wizard? - +## What is the Bluetooth File Transfer Wizard? The Bluetooth File Transfer Wizard enables users to transfer files between a computer and a Bluetooth device. For example, users can transfer files between a computer and a mobile phone or a personal digital assistant (PDA). The Bluetooth File Transfer Wizard can also transfer files between two computers that support Bluetooth. -**Note**  The default GUI that the Bluetooth File Transfer Wizard uses is implemented in the Fsquirt.exe file. This file can be unhooked from the underlying transfer wizard mechanism to enable replacement of the default Bluetooth File Transfer Wizard GUI. For more information, see the following question. - - - -## How do I unhook Fsquirt.exe? +> [!NOTE] +> The default GUI that the Bluetooth File Transfer Wizard uses is implemented in the Fsquirt.exe file. This file can be unhooked from the underlying transfer wizard mechanism to enable replacement of the default Bluetooth File Transfer Wizard GUI. For more information, see the following question. +## How do I unhook Fsquirt.exe? Software developers that desire to replace the in-box Bluetooth File Transfer Wizard with a proprietary application can unhook Fsquirt.exe from the underlying transfer wizard mechanism by performing the following steps: -1. Create a DWORD value that is named **DisableFsquirt** under the HKLM\\System\\CurrentControlSet\\Services\\Bthport\\Parameters key in the registry. -2. Set the value of **DisableFsquirt** to 0x1 -3. Either reboot or run the following command in a command prompt window: **fsquirt.exe -UnRegister** +1. Create a DWORD value that is named **DisableFsquirt** under the HKLM\\System\\CurrentControlSet\\Services\\Bthport\\Parameters key in the registry. +1. Set the value of **DisableFsquirt** to 0x1 +1. Either reboot or run the following command in a command prompt window: **fsquirt.exe -UnRegister** To re-enable Fsquirt.exe, perform the following steps: -1. Delete the **DisableFsquirt** value from the registry. -2. Reboot or run the following command in a command prompt window: **fsquirt.exe -Register** +1. Delete the **DisableFsquirt** value from the registry. +1. Reboot or run the following command in a command prompt window: **fsquirt.exe -Register** -## In Windows Vista, why does the Bluetooth notification area icon sometimes disappear? +## Why does the Bluetooth notification area icon sometimes disappear? - -In Windows Vista RTM and Windows Vista with SP1, the Bluetooth notification area icon appears when the Bluetooth radio is connected to the computer. The icon is configured to stay active for up to 10 minutes, but after that period the icon disappears from the notification area. +The Bluetooth notification area icon appears when the Bluetooth radio is connected to the computer. The icon is configured to stay active for up to 10 minutes, but after that period the icon disappears from the notification area. If users want a persistent Bluetooth notification area icon, they can select the **Show the Bluetooth icon in the notification area** check box on the **Options** tab of the Control Panel Bluetooth Settings application. -![bluetooth notification settings.](images/bluetoothnotificationsettings.jpg) - -**Note**  Even if no Bluetooth icon is in the notification area, you can still use the Control Panel Bluetooth Settings application to perform related tasks such as adding new Bluetooth devices, making the computer discoverable, and so on. - - +:::image type="content" source="images/bluetoothnotificationsettings.jpg" alt-text="Screenshot of the Options tab in Bluetooth Settings dialog box."::: -## Can vendors add tabs to the Control Panel Bluetooth Settings application? +> [!NOTE] +> Even if no Bluetooth icon is in the notification area, you can still use the Control Panel Bluetooth Settings application to perform related tasks such as adding new Bluetooth devices, making the computer discoverable, and so on. +## Can vendors add tabs to the Control Panel Bluetooth Settings application? Yes, vendors can add tabs by implementing a shell property sheet handler for the application. For example, IHVs that implement extensions to the in-box Bluetooth stack can implement a property sheet handler that adds tabs for profiles such as file transfer, enhancements added to version 2.1 of the Bluetooth specification, and so on. For more information about how to implement property sheet handlers, see [Property Sheet Handlers](/previous-versions/windows/desktop/legacy/cc144106(v=vs.85)). -## Why does Windows 7 and Windows Vista display a dialog box when a Bluetooth audio device is initially connected? - +## Why does Windows 7 and Windows Vista display a dialog box when a Bluetooth audio device is initially connected? Windows might not provide default support for headset (HSP), hands-free (HFP), or advanced audio distribution (A2DP) audio profiles. If a Bluetooth audio device is paired with a system that does not have the necessary drivers, Windows typically displays the **Found New Hardware** dialog box. However, the dialog box does not appear if one of the following is true: -- The computer’s OEM provided a profile pack that supports Bluetooth audio. -- The end user previously installed a Bluetooth headset and downloaded the audio drivers from media that the IHV or Windows Update provided. - -## How do I enhance the functionality and better represent my Bluetooth device in Devices and Printers? +- The computer's OEM provided a profile pack that supports Bluetooth audio. +- The end user previously installed a Bluetooth headset and downloaded the audio drivers from media that the IHV or Windows Update provided. +## How do I enhance the functionality and better represent my Bluetooth device in Devices and Printers? -You can create a device metadata package for your Bluetooth device so that Devices and Printers displays device-specific information about your device, such as photorealistic icons and custom descriptions. This can significantly improve a user’s experience with your Bluetooth device. For example, you might want to more effectively expose all the features that your device supports. Certain device classes can also take advantage of Device Stage, which enables IHVs to further enhance the device experience by providing a customized and branded device-specific user interface. +You can create a device metadata package for your Bluetooth device so that Devices and Printers displays device-specific information about your device, such as photorealistic icons and custom descriptions. This can significantly improve a user's experience with your Bluetooth device. For example, you might want to more effectively expose all the features that your device supports. Certain device classes can also take advantage of Device Stage, which enables IHVs to further enhance the device experience by providing a customized and branded device-specific user interface. For more information about how to create a device metadata package for your device, see [How to Create a Device Metadata Package for Devices and Printers](/previous-versions/windows/hardware/metadata/). -For more information about Device Stage, see **“Device Stage General Development Kit” on the MSDN Web site**. - -**Note**  To take advantage of Device Stage, the Device ID Profile must be implemented, which includes the Hardware ID, Vendor ID, and PID. - - - - +For more information about Device Stage, see **"Device Stage General Development Kit" on the MSDN Web site**. +> [!NOTE] +> To take advantage of Device Stage, the Device ID Profile must be implemented, which includes the Hardware ID, Vendor ID, and PID. diff --git a/windows-driver-docs-pr/bluetooth/building-and-sending-a-brb.md b/windows-driver-docs-pr/bluetooth/building-and-sending-a-brb.md index 7519931e49..75be6d5da6 100644 --- a/windows-driver-docs-pr/bluetooth/building-and-sending-a-brb.md +++ b/windows-driver-docs-pr/bluetooth/building-and-sending-a-brb.md @@ -1,37 +1,28 @@ --- -title: Building and Sending a BRB -description: Building and Sending a BRB +title: Building and sending a Bluetooth request block (BRB) +description: Building and sending a Bluetooth request block (BRB) keywords: - Bluetooth WDK , Bluetooth request blocks - BRBs WDK - Bluetooth WDK , request blocks - sending BRBs - return values WDK Bluetooth -ms.date: 04/20/2017 +ms.date: 10/06/2022 --- -# Building and Sending a BRB - +# Building and sending a Bluetooth request block (BRB) The following procedure outlines the general process that a profile driver follows to build and send a Bluetooth request block (BRB). A BRB is a block of data that describes the Bluetooth operation to perform. -### To Build and Send a BRB - -1. Allocate an IRP. For more information about how to use IRPs, see [Handling IRPs](../kernel/handling-irps.md). - -2. Allocate a BRB. To allocate BRBs, call the [**BthAllocateBrb**](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnbth_allocate_brb) function that the Bluetooth driver stack exports for use by profile drivers. To obtain a pointer to the *BthAllocateBrb* function, see [Querying for Bluetooth Interfaces](querying-for-bluetooth-interfaces.md). - -3. Initialize the parameters of the BRB. Each BRB uses a corresponding structure. Set the members of the structure according to the intended use. For a list of BRBs and their corresponding structures see [Using the Bluetooth Driver Stack](using-the-bluetooth-driver-stack.md). - -4. Initialize the parameters of the IRP. Set the **MajorFunction** member of the IRP to IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL. Set the **Parameters.DeviceIoControl.IoControlCode** member to IOCTL\_INTERNAL\_BTH\_SUBMIT\_BRB. Set the **Parameters.Others.Argument1** member to point to the BRB. +## To build and send a BRB -5. Pass the IRP down the driver stack. Call [**IoCallDriver**](/windows-hardware/drivers/ddi/wdm/nf-wdm-iocalldriver) to send the IRP to the next-lower driver. +1. Allocate an IRP. For more information about how to use IRPs, see [Handling IRPs](../kernel/handling-irps.md). +1. Allocate a BRB. To allocate BRBs, call the [**BthAllocateBrb**](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnbth_allocate_brb) function that the Bluetooth driver stack exports for use by profile drivers. To obtain a pointer to the *BthAllocateBrb* function, see [Querying for Bluetooth Interfaces](querying-for-bluetooth-interfaces.md). +1. Initialize the parameters of the BRB. Each BRB uses a corresponding structure. Set the members of the structure according to the intended use. For a list of BRBs and their corresponding structures see [Using the Bluetooth Driver Stack](using-the-bluetooth-driver-stack.md). +1. Initialize the parameters of the IRP. Set the **MajorFunction** member of the IRP to IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL. Set the **Parameters.DeviceIoControl.IoControlCode** member to IOCTL\_INTERNAL\_BTH\_SUBMIT\_BRB. Set the **Parameters.Others.Argument1** member to point to the BRB. +1. Pass the IRP down the driver stack. Call [**IoCallDriver**](/windows-hardware/drivers/ddi/wdm/nf-wdm-iocalldriver) to send the IRP to the next-lower driver. -The following pseudocode example demonstrates how to set up a L2CAP Ping BRB for the Bluetooth driver stack to process. - -**Note**  For readability, the following pseudocode example does not demonstrate error handling. - - +The following pseudocode example demonstrates how to set up a L2CAP Ping BRB for the Bluetooth driver stack to process. For readability, the example does not demonstrate error handling. ```cpp #include @@ -61,6 +52,3 @@ NextIrpStack->Parameters.Others.Argument1 = BrbPing; NTSTATUS Status; Status = IoCallDriver( DeviceExtension->NextLowerDriver, Irp ); ``` - - - diff --git a/windows-driver-docs-pr/bluetooth/creating-a-sco-client-connection-to-a-remote-device.md b/windows-driver-docs-pr/bluetooth/creating-a-sco-client-connection-to-a-remote-device.md index 63df0f23eb..becd7dfbe8 100644 --- a/windows-driver-docs-pr/bluetooth/creating-a-sco-client-connection-to-a-remote-device.md +++ b/windows-driver-docs-pr/bluetooth/creating-a-sco-client-connection-to-a-remote-device.md @@ -5,31 +5,24 @@ keywords: - Synchronous Connection-Oriented WDK Bluetooth - SCO profile drivers WDK Bluetooth - initiating SCO connections -ms.date: 04/20/2017 +ms.date: 09/22/2022 --- # Creating a SCO Client Connection to a Remote Device - A SCO client profile driver is a profile driver that requests Synchronous Connection-Oriented (SCO) connection to a remote device. If the device accepts the connection, the SCO client profile driver is notified of any changes to the connection. For example, a SCO client profile driver can request a connection to a remote headset, and after the headset accepts the connection request, the Bluetooth driver stack can notify the profile driver when the headset is turned off or removed. Because SCO connections are point-to-point connections between two Bluetooth devices, a SCO client profile driver needs only the Bluetooth address of the remote device to connect to. -To initiate a SCO connection to a remote device, profile drivers should [build and send](building-and-sending-a-brb.md) a [**BRB\_SCO\_OPEN\_CHANNEL**](/previous-versions/ff536626(v=vs.85)) request. - -If the remote device accepts the profile driver's SCO connection request, the profile driver can then perform additional BRB commands across the newly connected channel by using IOCTL\_INTERNAL\_BTH\_SUBMIT\_BRB, including: - -- [**BRB\_SCO\_GET\_CHANNEL\_INFO**](/previous-versions/ff536624(v=vs.85)) - -- [**BRB\_SCO\_GET\_SYSTEM\_INFO**](/previous-versions/ff536625(v=vs.85)) - -- [**BRB\_SCO\_TRANSFER**](/previous-versions/ff536629(v=vs.85)) - -**Note**  Profile drivers should [build and send](building-and-sending-a-brb.md) a **BRB\_SCO\_GET\_SYSTEM\_INFO** request during initialization to determine if the underlying hardware supports SCO and, if so, what the global SCO settings are. +To initiate a SCO connection to a remote device, profile drivers should [build and send](building-and-sending-a-brb.md) a [_BRB_SCO_OPEN_CHANNEL](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_brb_sco_open_channel) request. - +If the remote device accepts the profile driver's SCO connection request, the profile driver can then perform additional BRB commands across the newly connected channel by using [**IOCTL_INTERNAL_BTH_SUBMIT_BRB**](/windows-hardware/drivers/ddi/bthioctl/ni-bthioctl-ioctl_internal_bth_submit_brb) to submit a Bluetooth Request Block (BRB) to the Bluetooth driver stack, including: -When the profile driver no longer requires the SCO connection to the remote device, it should [build and send](building-and-sending-a-brb.md) a [**BRB\_SCO\_CLOSE\_CHANNEL**](/previous-versions/ff536622(v=vs.85)) request. +- [_BRB_SCO_GET_CHANNEL_INFO](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_brb_sco_get_channel_info) +- [_BRB_SCO_GET_SYSTEM_INFO](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_brb_sco_get_system_info) +- [_BRB_SCO_TRANSFER](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_brb_sco_transfer) - +> [!NOTE] +> Profile drivers should [build and send](building-and-sending-a-brb.md) a **BRB_SCO_GET_SYSTEM_INFO** request during initialization to determine if the underlying hardware supports SCO and, if so, what the global SCO settings are. +When the profile driver no longer requires the SCO connection to the remote device, it should [build and send](building-and-sending-a-brb.md) a [_BRB_SCO_CLOSE_CHANNEL](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_brb_sco_close_channel) request. diff --git a/windows-driver-docs-pr/bluetooth/general-bluetooth-support-in-windows.md b/windows-driver-docs-pr/bluetooth/general-bluetooth-support-in-windows.md index 44d7101aa5..a2bc440833 100644 --- a/windows-driver-docs-pr/bluetooth/general-bluetooth-support-in-windows.md +++ b/windows-driver-docs-pr/bluetooth/general-bluetooth-support-in-windows.md @@ -1,7 +1,9 @@ --- title: Bluetooth version and profile support in Windows 11 description: Provides information about Bluetooth version and profile support in Windows 11 -ms.date: 03/08/2022 +ms.date: 07/12/2023 +content_well_notification: + - AI-contribution --- # Bluetooth version and profile support in Windows 11 @@ -9,20 +11,17 @@ ms.date: 03/08/2022 > [!NOTE] > Looking for drivers for your Bluetooth audio device? See [Fix connections to Bluetooth audio devices and wireless displays](https://go.microsoft.com/fwlink/p/?LinkID=623629). -> [!NOTE] -> For information about Bluetooth support prior to Windows 11, see [Bluetooth Support in Previous Windows Versions](bluetooth-support-in-previous-windows-versions.md). - ## Which Bluetooth versions does Windows 11 support? -Windows 11 supports Bluetooth Core Specification version 5.1. +Windows 11 version 22H2, all editions support Bluetooth Core Specification version 5.3. -Windows Server 2019 does not support Bluetooth. +Windows Server **does not** have in-box Bluetooth wireless technology support. Third-party Bluetooth drivers might be available from independent hardware vendors (IHVs). ## Which Bluetooth profiles have in-box support in Windows 11? ### Core specification -Windows 11 supports Bluetooth core specification 5.1, including the following: +Windows 11 supports Bluetooth core specification 5.3, including the following: | Profile or protocol | Abbreviation | |--------------------------------------------|--------------| @@ -37,15 +36,17 @@ Windows 11 supports Bluetooth core specification 5.1, including the following: ### GATT profiles and services -| Profile or service | Abbreviation | Version | -|--------------------------------|--------------|---------| -| Device Information Service | DIS | 1.1 | -| HID over GATT Profile | HOGP | 1.0 | -| Scan Parameters Profile client | ScPP | 2.1 | +| Profile or service | Abbreviation | Version | +|----------------------------------|--------------|---------| +| Device Information Service | DIS | 1.1 | +| Generic Media Control Service | GMCS | 1.0 | +| Generic Telephone Bearer Service | GTBS | 1.0 | +| HID over GATT Profile | HOGP | 1.0 | +| Scan Parameters Profile client | ScPP | 2.1 | -### Traditional Bluetooth profiles and protocols +### Bluetooth profiles and protocols -Windows 11 (version 21H2) supports Bluetooth version 5.1 and the following Bluetooth profiles and protocols: +Windows 11 version 22H2 supports Bluetooth version 5.3 and the following Bluetooth profiles and protocols: | Profile or protocol | Abbreviation | Version | |---------------------------------------------|--------------|---------| @@ -53,22 +54,31 @@ Windows 11 (version 21H2) supports Bluetooth version 5.1 and the following Bluet | Audio/Video Control Transport Protocol | AVCTP | 1.4 | | Audio Video Distribution Transport Protocol | AVDTP | 1.3 | | A/V Remote Control Profile | AVRCP | 1.6.2 | +| Basic Audio Profile | BAP | 1.0.1 | | Bluetooth Network Encapsulation Protocol | BNEP | 1.0 | +| Call Control Profile | CCP | 1.0 | +| Common Audio Profile | CAP | 1.0 | +| Coordinated Set Identification Profile | CSIP | 1.0.1 | | Device ID | DID | 1.3 | | Dial Up Networking Profile | DUN | 1.1 | | Generic A/V Distribution Profile | GAVDP | 1.3 | | Hands-Free Profile | HFP | 1.7.2 | | Hard Copy Replacement Profile 1.2 | HRCP | 1.1 | +| Hearing Access Profile | HAP | 1.0 | | Human Interface Device | HID | 1.1.1 | +| Media Control Profile | MCP | 1.0 | +| Microphone Control Profile | MICP | 1.0 | | Object Push Profile | OPP | 1.1 | | Personal Area Network Profile | PAN | 1.0 | | Radio Frequency Communication | RFCOMM | 1.1 | | Serial Port Profile | SPP | 1.2 | +| Telephony and Media Audio Profile | TMAP | 1.0 | +| Volume Control Profile | VCP | 1.0 | -## New features and recommendations for Windows 11 and later +## New features and recommendations for Windows 11 version 22H2 and later To learn more about the new features and hardware developer recommendations for the different versions of Windows 11, see [Bluetooth](/windows-hardware/design/component-guidelines/bluetooth) in the [Hardware component guidelines](/windows-hardware/design/component-guidelines/components) section. ## Related topics -[Bluetooth Support in Previous Windows Versions](bluetooth-support-in-previous-windows-versions.md) +- [Bluetooth Support in Previous Windows Versions](bluetooth-support-in-previous-windows-versions.md) diff --git a/windows-driver-docs-pr/bluetooth/images/BTP-PMOD.PNG b/windows-driver-docs-pr/bluetooth/images/BTP-PMOD.PNG deleted file mode 100644 index 25f5350c24..0000000000 Binary files a/windows-driver-docs-pr/bluetooth/images/BTP-PMOD.PNG and /dev/null differ diff --git a/windows-driver-docs-pr/bluetooth/images/ESP32Reset.png b/windows-driver-docs-pr/bluetooth/images/ESP32Reset.png deleted file mode 100644 index 5e1b075d06..0000000000 Binary files a/windows-driver-docs-pr/bluetooth/images/ESP32Reset.png and /dev/null differ diff --git a/windows-driver-docs-pr/bluetooth/images/HCI_Example_Filters_Sampling.png b/windows-driver-docs-pr/bluetooth/images/HCI_Example_Filters_Sampling.png deleted file mode 100644 index ed03893ace..0000000000 Binary files a/windows-driver-docs-pr/bluetooth/images/HCI_Example_Filters_Sampling.png and /dev/null differ diff --git a/windows-driver-docs-pr/bluetooth/images/HCI_VS_MSFT_LE_Monitor_Advertisement_State_Diagram.png b/windows-driver-docs-pr/bluetooth/images/HCI_VS_MSFT_LE_Monitor_Advertisement_State_Diagram.png deleted file mode 100644 index 97f1556b7b..0000000000 Binary files a/windows-driver-docs-pr/bluetooth/images/HCI_VS_MSFT_LE_Monitor_Advertisement_State_Diagram.png and /dev/null differ diff --git a/windows-driver-docs-pr/bluetooth/images/HCI_VS_MSFT_LE_Monitor_Advertisement_State_Diagram.svg b/windows-driver-docs-pr/bluetooth/images/HCI_VS_MSFT_LE_Monitor_Advertisement_State_Diagram.svg new file mode 100644 index 0000000000..4ecc3ee50e --- /dev/null +++ b/windows-driver-docs-pr/bluetooth/images/HCI_VS_MSFT_LE_Monitor_Advertisement_State_Diagram.svg @@ -0,0 +1,256 @@ + + + + + HCI_VS_MSFT_LE_Monitor_Advertisement_State_Diagram + + + + + + + + + + + + + + + + + + + + + + + + + HCI_VS_MSFT_LE_Monitor_Advertisement_State_Diagram + + + + + + + + + + + + + Start state + Initial Radio state, not monitoring + + Sheet.2 + + + + Sheet.3 + + + + + + Initial Radio state,not monitoring + + + State + Monitoring, device not in range + + + + + + + + + + + + Monitoring,device not in range + + State.5 + Monitoring, in range event sent to Host + + + + + + + + + + + + Monitoring, in range event sent to Host + + Center to center 1.7 + + + + + + + + Center to center 1 + + + + + + + + Loop on center + + + + + + + + Sheet.12 + Event: VSC received Action: Start monitoring + + + + Event:VSC receivedAction:Start monitoring + + Sheet.15 + Event: VSC received to stop monitoring Action: Stop monitoring + + + + Event:VSC received to stop monitoringAction: Stop monitoring + + Sheet.18 + Event: RSSI received < RSSI_threshold_high Action: None + + + + Event:RSSI received < RSSI_threshold_highAction: None + + Center to center 1.19 + + + + + + + + Sheet.20 + Event: VSC received to stop monitoring Action: Stop Periodic ... + + + + Event: VSC received to stop monitoringAction: Stop Periodic TimerStop LowThresholdTimerStop monitoring + + Center to center 1.22 + + + + + + + + Center to center 1.31 + + + + + + + + Sheet.32 + Event: LowThresholdTimer expires Action: Generate HCI_VS_MSFT... + + + + Event:LowThresholdTimer expiresAction: Generate HCI_VS_MSFT_Monitor_Device_EventStop Periodic TimerNotified = 0 + + Center to center 1.35 + + + + + + + + Sheet.36 + Event: Advertisement packet received && RSSI > RSSI_threshold... + + + + Event:Advertisement packet received && RSSI > RSSI_threshold_lowAction: Restart LowThresholdTimerEvent: Advertisement packet received && RSSI <= RSSI_threshold_lowAction: NoneEvent: Periodic Timer expiresAction: If (Advertisement_Filter_Enable == 1 && Advertisement matches Advertisement_report_filtering_options)Propagate received advertisement to the Host with average RSSI received during this sampling periodEvent: Advertisement packet received && RSSI_sampling_period == 0x00Action: If (Advertisement_Filter_Enable == 1 && Advertisement matches Advertisement_report_filtering_options)Propagate received advertisement to the Host + + Sheet.23 + Event: RSSI received >= RSSI_threshold_high && (Notified == 0... + + + + Event:RSSI received >= RSSI_threshold_high && (Notified == 0) && Advertisement matches condition and Monitor_optionsAction: Generate HCI_VS_MSFT_Monitor_Device_EventNotified = 1Start LowThresholdTimerIf RSSI_sampling_period != (0x00 || 0xFF)Start Periodic TimerIf (Advertisement_Filter_Enable == 1 && Advertisement matches Advertisement_report_filtering_options)Propagate received advertisement to the Host + + diff --git a/windows-driver-docs-pr/bluetooth/images/RN42Schematic.png b/windows-driver-docs-pr/bluetooth/images/RN42Schematic.png deleted file mode 100644 index 20ae279da4..0000000000 Binary files a/windows-driver-docs-pr/bluetooth/images/RN42Schematic.png and /dev/null differ diff --git a/windows-driver-docs-pr/bluetooth/images/RN52Schematic.png b/windows-driver-docs-pr/bluetooth/images/RN52Schematic.png deleted file mode 100644 index 865d195790..0000000000 Binary files a/windows-driver-docs-pr/bluetooth/images/RN52Schematic.png and /dev/null differ diff --git a/windows-driver-docs-pr/bluetooth/images/Traduci_JumperSide.jpg b/windows-driver-docs-pr/bluetooth/images/Traduci_JumperSide.jpg deleted file mode 100644 index 258041a7f1..0000000000 Binary files a/windows-driver-docs-pr/bluetooth/images/Traduci_JumperSide.jpg and /dev/null differ diff --git a/windows-driver-docs-pr/bluetooth/images/WindowsStoreArduinoIDE.png b/windows-driver-docs-pr/bluetooth/images/WindowsStoreArduinoIDE.png deleted file mode 100644 index a83408ff5f..0000000000 Binary files a/windows-driver-docs-pr/bluetooth/images/WindowsStoreArduinoIDE.png and /dev/null differ diff --git a/windows-driver-docs-pr/bluetooth/images/bap-configuration-1.png b/windows-driver-docs-pr/bluetooth/images/bap-configuration-1.png new file mode 100644 index 0000000000..764b2b55ff Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/bap-configuration-1.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/bap-configuration-2.png b/windows-driver-docs-pr/bluetooth/images/bap-configuration-2.png new file mode 100644 index 0000000000..1c4827f249 Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/bap-configuration-2.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/bap-configuration-3.png b/windows-driver-docs-pr/bluetooth/images/bap-configuration-3.png new file mode 100644 index 0000000000..4cbf90df35 Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/bap-configuration-3.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/bap-configuration-4.png b/windows-driver-docs-pr/bluetooth/images/bap-configuration-4.png new file mode 100644 index 0000000000..24d585157f Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/bap-configuration-4.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/bap-configuration-5.png b/windows-driver-docs-pr/bluetooth/images/bap-configuration-5.png new file mode 100644 index 0000000000..1a6b148e21 Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/bap-configuration-5.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/bap-configuration-6-i.png b/windows-driver-docs-pr/bluetooth/images/bap-configuration-6-i.png new file mode 100644 index 0000000000..60767d1da3 Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/bap-configuration-6-i.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/bap-configuration-6-ii.png b/windows-driver-docs-pr/bluetooth/images/bap-configuration-6-ii.png new file mode 100644 index 0000000000..ffa8842e93 Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/bap-configuration-6-ii.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/bap-configuration-7-i.png b/windows-driver-docs-pr/bluetooth/images/bap-configuration-7-i.png new file mode 100644 index 0000000000..67a37b82a6 Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/bap-configuration-7-i.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/bap-configuration-8-i.png b/windows-driver-docs-pr/bluetooth/images/bap-configuration-8-i.png new file mode 100644 index 0000000000..49f83db635 Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/bap-configuration-8-i.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/bap-configuration-8-ii.png b/windows-driver-docs-pr/bluetooth/images/bap-configuration-8-ii.png new file mode 100644 index 0000000000..3d58bd4b2c Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/bap-configuration-8-ii.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/bap-configuration-9-i.png b/windows-driver-docs-pr/bluetooth/images/bap-configuration-9-i.png new file mode 100644 index 0000000000..696f95cd58 Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/bap-configuration-9-i.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/bap-configuration-9-ii.png b/windows-driver-docs-pr/bluetooth/images/bap-configuration-9-ii.png new file mode 100644 index 0000000000..86868b4a6b Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/bap-configuration-9-ii.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/bluetooth-le-audio-architecture-with-lc3-codec-in-audio-driver-stack.png b/windows-driver-docs-pr/bluetooth/images/bluetooth-le-audio-architecture-with-lc3-codec-in-audio-driver-stack.png new file mode 100644 index 0000000000..d66ba6b52f Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/bluetooth-le-audio-architecture-with-lc3-codec-in-audio-driver-stack.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/bluetooth-le-audio-architecture-with-lc3-codec-in-bluetooth-controller.png b/windows-driver-docs-pr/bluetooth/images/bluetooth-le-audio-architecture-with-lc3-codec-in-bluetooth-controller.png new file mode 100644 index 0000000000..86beaa19f8 Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/bluetooth-le-audio-architecture-with-lc3-codec-in-bluetooth-controller.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/bluetooth-le-audio-vendor-specific-inband-architecture.png b/windows-driver-docs-pr/bluetooth/images/bluetooth-le-audio-vendor-specific-inband-architecture.png new file mode 100644 index 0000000000..55b8c2f7ff Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/bluetooth-le-audio-vendor-specific-inband-architecture.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/bluetooth-le-audio-with-audio-offload-architecture-with-lc3-codec-in-audio-dsp.png b/windows-driver-docs-pr/bluetooth/images/bluetooth-le-audio-with-audio-offload-architecture-with-lc3-codec-in-audio-dsp.png new file mode 100644 index 0000000000..d0183fe222 Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/bluetooth-le-audio-with-audio-offload-architecture-with-lc3-codec-in-audio-dsp.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/bluetooth-le-audio-with-audio-offload-architecture-with-lc3-codec-in-bluetooth-controller.png b/windows-driver-docs-pr/bluetooth/images/bluetooth-le-audio-with-audio-offload-architecture-with-lc3-codec-in-bluetooth-controller.png new file mode 100644 index 0000000000..fbc92715d0 Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/bluetooth-le-audio-with-audio-offload-architecture-with-lc3-codec-in-bluetooth-controller.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/bluetooth_architecture.png b/windows-driver-docs-pr/bluetooth/images/bluetooth_architecture.png deleted file mode 100644 index 93e6b9b0a0..0000000000 Binary files a/windows-driver-docs-pr/bluetooth/images/bluetooth_architecture.png and /dev/null differ diff --git a/windows-driver-docs-pr/bluetooth/images/btle-audio-driver-init-seq.png b/windows-driver-docs-pr/bluetooth/images/btle-audio-driver-init-seq.png new file mode 100644 index 0000000000..3daac0ac95 Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/btle-audio-driver-init-seq.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/btle-audio-endpoint-creation.png b/windows-driver-docs-pr/bluetooth/images/btle-audio-endpoint-creation.png new file mode 100644 index 0000000000..51dfed5496 Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/btle-audio-endpoint-creation.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/btle-audio-endpoint-removal.png b/windows-driver-docs-pr/bluetooth/images/btle-audio-endpoint-removal.png new file mode 100644 index 0000000000..053d14ef89 Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/btle-audio-endpoint-removal.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/btle-audio-stream-creation.png b/windows-driver-docs-pr/bluetooth/images/btle-audio-stream-creation.png new file mode 100644 index 0000000000..87d55ad9e4 Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/btle-audio-stream-creation.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/btle-audio-stream-pause-profile-circuit.png b/windows-driver-docs-pr/bluetooth/images/btle-audio-stream-pause-profile-circuit.png new file mode 100644 index 0000000000..1cca7f3c05 Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/btle-audio-stream-pause-profile-circuit.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/btle-audio-stream-pause-streaming-circuit.png b/windows-driver-docs-pr/bluetooth/images/btle-audio-stream-pause-streaming-circuit.png new file mode 100644 index 0000000000..af227a3df1 Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/btle-audio-stream-pause-streaming-circuit.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/btle-audio-stream-preparation-profile-circuit.png b/windows-driver-docs-pr/bluetooth/images/btle-audio-stream-preparation-profile-circuit.png new file mode 100644 index 0000000000..1ac8e4fc13 Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/btle-audio-stream-preparation-profile-circuit.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/btle-audio-stream-preparation-streaming-circuit.png b/windows-driver-docs-pr/bluetooth/images/btle-audio-stream-preparation-streaming-circuit.png new file mode 100644 index 0000000000..d87eaa683c Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/btle-audio-stream-preparation-streaming-circuit.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/btle-audio-stream-release-profile-circuit.png b/windows-driver-docs-pr/bluetooth/images/btle-audio-stream-release-profile-circuit.png new file mode 100644 index 0000000000..50f70829e6 Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/btle-audio-stream-release-profile-circuit.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/btle-audio-stream-release-streaming-circuit.png b/windows-driver-docs-pr/bluetooth/images/btle-audio-stream-release-streaming-circuit.png new file mode 100644 index 0000000000..066f7da646 Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/btle-audio-stream-release-streaming-circuit.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/btle-audio-stream-start-profile-circuit.png b/windows-driver-docs-pr/bluetooth/images/btle-audio-stream-start-profile-circuit.png new file mode 100644 index 0000000000..736b9425c8 Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/btle-audio-stream-start-profile-circuit.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/btle-audio-stream-start-streaming-circuit.png b/windows-driver-docs-pr/bluetooth/images/btle-audio-stream-start-streaming-circuit.png new file mode 100644 index 0000000000..fcac9afb6b Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/btle-audio-stream-start-streaming-circuit.png differ diff --git a/windows-driver-docs-pr/bluetooth/images/download.PNG b/windows-driver-docs-pr/bluetooth/images/download.PNG deleted file mode 100644 index 9fdbccc2ad..0000000000 Binary files a/windows-driver-docs-pr/bluetooth/images/download.PNG and /dev/null differ diff --git a/windows-driver-docs-pr/bluetooth/images/esp32_topdown.png b/windows-driver-docs-pr/bluetooth/images/esp32_topdown.png deleted file mode 100644 index f194e0dd06..0000000000 Binary files a/windows-driver-docs-pr/bluetooth/images/esp32_topdown.png and /dev/null differ diff --git a/windows-driver-docs-pr/bluetooth/images/microsoft-defined-bluetooth-hci-commands-and-events-diagrams.vsdx b/windows-driver-docs-pr/bluetooth/images/microsoft-defined-bluetooth-hci-commands-and-events-diagrams.vsdx new file mode 100644 index 0000000000..749933caff Binary files /dev/null and b/windows-driver-docs-pr/bluetooth/images/microsoft-defined-bluetooth-hci-commands-and-events-diagrams.vsdx differ diff --git a/windows-driver-docs-pr/bluetooth/implementing-a-bluetooth-le-proximity-profile-device-and-application.md b/windows-driver-docs-pr/bluetooth/implementing-a-bluetooth-le-proximity-profile-device-and-application.md index 529264fe9b..dff5f60f69 100644 --- a/windows-driver-docs-pr/bluetooth/implementing-a-bluetooth-le-proximity-profile-device-and-application.md +++ b/windows-driver-docs-pr/bluetooth/implementing-a-bluetooth-le-proximity-profile-device-and-application.md @@ -1,34 +1,23 @@ --- -title: Bluetooth LE Proximity Profile Overview +title: Bluetooth LE Proximity Profile overview description: Proximity detection is a common use of Bluetooth Low Energy (LE). -ms.date: 07/01/2019 +ms.date: 10/06/2022 --- -# Bluetooth LE Proximity Profile Overview +# Bluetooth LE Proximity Profile overview - -Proximity detection is a common use of Bluetooth Low Energy (LE). Windows 8.1 expands on the Bluetooth LE support introduced in Windows 8. This section provides guidelines to create a device implementation of the Proximity Profile that you can use to develop a UWP device app that's compatible with Windows 8.1. +Proximity detection is a common use of Bluetooth Low Energy (LE). This section provides guidelines to create a device implementation of the Proximity Profile that you can use to develop a UWP device app. Before you develop this app, you should be familiar with Bluetooth LE functions and the Bluetooth LE Proximity profile specification. -## Example Service Declaration - +## Example service declaration -Bluetooth Low Energy introduced a new physical layer that shares the same frequency space as Bluetooth Basic Rate. Low Energy Profiles are organized into what’s called the Generic Attribute Profile (or GATT). +Bluetooth Low Energy introduced a new physical layer that shares the same frequency space as Bluetooth Basic Rate. Low energy profiles are organized into what's called the Generic Attribute Profile (or GATT). -A GATT profile declares one or more services that define a use case or scenario. To develop a compliant service implementation, you must organize *characteristics* so that they conform to the established schema defined on the [Bluetooth Special Interest Group (SIG) developer website](https://go.microsoft.com/fwlink/p/?linkid=320723). +A GATT profile declares one or more services that define a use case or scenario. To develop a compliant service implementation, you must organize *characteristics* so that they conform to the established schema defined on the [Bluetooth Special Interest Group (SIG) developer website](https://www.bluetooth.com/develop-with-bluetooth/). This diagram shows how *characteristics* are structured inside a typical GATT service. -![example gatt service declaration.](images/bthleservicedeclaration.png) +:::image type="content" source="images/bthleservicedeclaration.png" alt-text="Diagram showing a GATT service declaration example."::: An example proximity profile is described further in [Bluetooth Proximity Profile](bluetooth-proximity-profile.md). - - - - - - - - - diff --git a/windows-driver-docs-pr/bluetooth/microsoft-defined-bluetooth-hci-commands-and-events.md b/windows-driver-docs-pr/bluetooth/microsoft-defined-bluetooth-hci-commands-and-events.md index d6e38b3ab2..83ce07b627 100644 --- a/windows-driver-docs-pr/bluetooth/microsoft-defined-bluetooth-hci-commands-and-events.md +++ b/windows-driver-docs-pr/bluetooth/microsoft-defined-bluetooth-hci-commands-and-events.md @@ -1,20 +1,20 @@ --- title: Microsoft-defined Bluetooth HCI commands and events description: The Bluetooth Host-Controller Interface (HCI) specifies all interactions between a host and a Bluetooth radio controller. -ms.date: 11/10/2021 +ms.date: 04/17/2023 --- # Microsoft-defined Bluetooth HCI extensions -The Bluetooth Host-Controller Interface (HCI) specifies all interactions between a host and a Bluetooth radio controller. Bluetooth specifications allow vendor-defined HCI commands and events to enable non-standardized interaction between hosts and controllers. Microsoft defines vendor-specific HCI commands and events that are consumed by Windows. Bluetooth controller implementers can use these extensions to implement special features. +The Bluetooth Host-Controller Interface (HCI) specifies all interactions between a host and a Bluetooth radio controller. Bluetooth specifications allow vendor-defined HCI commands and events to enable nonstandardized interaction between hosts and controllers. Microsoft defines vendor-specific HCI commands and events that are consumed by Windows. Bluetooth controller implementers can use these extensions to implement special features. ## Requirements Bluetooth HCI commands are identified by a 16-bit command code. The Bluetooth organization defines values in the range 0x0000 through 0xFBFF. Vendors define values in the range 0xFC00 through 0xFFFF, allowing for 1024 different possible vendor-assigned command codes. -The vendor must choose the value of the Microsoft-defined command code. Microsoft can't choose a command code and assume that no other vendor uses the code for a conflicting purpose. It is unsafe to issue a vendor-specific command and depend on the controller to reject the command if it does not understand it. The controller could interpret the command as a destructive operation such as updating the controller's firmware. +The vendor must choose the value of the Microsoft-defined command code. Microsoft can't choose a command code and assume that no other vendor uses the code for a conflicting purpose. It's unsafe to issue a vendor-specific command and depend on the controller to reject the command if it doesn't understand it. The controller could interpret the command as a destructive operation such as updating the controller's firmware. -The vendor must communicate the chosen value through a method other than the controller. Microsoft does not specify how to get the chosen code. +The vendor must communicate the chosen value through a method other than the controller. Microsoft doesn't specify how to get the chosen code. ### Notifying Windows Bluetooth stack of the vendor specific command code @@ -39,21 +39,21 @@ HKR,,"VsMsftOpCode",0x00010001, ## Microsoft-defined HCI commands -|HCI Commands|Description| -|---|---| -|[HCI_VS_MSFT_Read_Supported_Features][ref_HCI_VS_MSFT_Read_Supported_Features] | Provides a bitmap that describes which Microsoft-defined features the controller supports, and specifies the prefix for Microsoft-defined events that are returned by the controller.| -|[HCI_VS_MSFT_Monitor_Rssi][ref_HCI_VS_MSFT_Monitor_Rssi] | Requests that the controller starts monitoring the measured link RSSI for a specified connection, and generates an event when the connection's measured link RSSI goes outside of the specified bounds.| -|[HCI_VS_MSFT_Cancel_Monitor_Rssi][ref_HCI_VS_MSFT_Cancel_Monitor_Rssi] | Cancels a previously-issued [HCI_VS_MSFT_Monitor_Rssi][ref_HCI_VS_MSFT_Monitor_Rssi] command.| -|[HCI_VS_MSFT_LE_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Monitor_Advertisement] | Requests that the controller starts monitoring for advertisements that fall within the specified RSSI range and also satisfy other requirements.| -|[HCI_VS_MSFT_LE_Cancel_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Cancel_Monitor_Advertisement] | Cancels a previously-issued [HCI_VS_MSFT_LE_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Monitor_Advertisement] command.| -|[HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable][ref_HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable] | Sets the state of the advertisement filters.| -|[HCI_VS_MSFT_Read_Absolute_RSSI][ref_HCI_VS_MSFT_Read_Absolute_RSSI]| Reads the absolute Received Signal Strength Indication (RSSI) value for a BR/EDR connection from the controller.| +| HCI Commands | Description | +|--|--| +| [HCI_VS_MSFT_Read_Supported_Features][ref_HCI_VS_MSFT_Read_Supported_Features] | Provides a bitmap that describes which Microsoft-defined features the controller supports, and specifies the prefix for Microsoft-defined events that are returned by the controller. | +| [HCI_VS_MSFT_Monitor_Rssi][ref_HCI_VS_MSFT_Monitor_Rssi] | Requests that the controller starts monitoring the measured link RSSI for a specified connection, and generates an event when the connection's measured link RSSI goes outside of the specified bounds. | +| [HCI_VS_MSFT_Cancel_Monitor_Rssi][ref_HCI_VS_MSFT_Cancel_Monitor_Rssi] | Cancels a previously issued [HCI_VS_MSFT_Monitor_Rssi][ref_HCI_VS_MSFT_Monitor_Rssi] command. | +| [HCI_VS_MSFT_LE_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Monitor_Advertisement] | Requests that the controller starts monitoring for advertisements that fall within the specified RSSI range and also satisfy other requirements. | +| [HCI_VS_MSFT_LE_Cancel_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Cancel_Monitor_Advertisement] | Cancels a previously issued [HCI_VS_MSFT_LE_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Monitor_Advertisement] command. | +| [HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable][ref_HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable] | Sets the state of the advertisement filters. | +| [HCI_VS_MSFT_Read_Absolute_RSSI][ref_HCI_VS_MSFT_Read_Absolute_RSSI] | Reads the absolute Received Signal Strength Indication (RSSI) value for a BR/EDR connection from the controller. | ### Microsoft-defined HCI command and subcommands -The controller understands there is only one Microsoft-specific HCI command. The Microsoft-specific command set is extended through the use of an opcode. The first command parameter for the Microsoft-defined HCI command is an opcode that specifies the subcommand. +The controller understands there's only one Microsoft-specific HCI command. The Microsoft-specific command set is extended by using an opcode. The first command parameter for the Microsoft-defined HCI command is an opcode that specifies the subcommand. -Controllers must support [HCI_VS_MSFT_Read_Supported_Features][ref_HCI_VS_MSFT_Read_Supported_Features] in order to support any other Microsoft HCI subcommands. Support for other commands is optional and depends on the values returned by HCI_VS_MSFT_Read_Supported_Features. Windows does not send any Microsoft-defined subcommands unless the controller indicates support for the subcommand through a response to HCI_VS_MSFT_Read_Supported_Features. +Controllers must support [HCI_VS_MSFT_Read_Supported_Features][ref_HCI_VS_MSFT_Read_Supported_Features] in order to support any other Microsoft HCI subcommands. Support for other commands is optional and depends on the values returned by HCI_VS_MSFT_Read_Supported_Features. Windows doesn't send any Microsoft-defined subcommands unless the controller indicates support for the subcommand through a response to HCI_VS_MSFT_Read_Supported_Features. ### HCI_VS_MSFT_Read_Supported_Features @@ -64,58 +64,60 @@ HCI_VS_MSFT_Read_Supported_Features provides a bitmap that describes which Micro The controller shall always complete this command promptly with a Command Completed event. | Command | Code | Command parameters | Return parameters | -|---|---|---|---| -|HCI_VS_MSFT_Read_Supported_Features|Chosen base code|Subcommand_opcode|Status,
Subcommand_opcode,
Supported_features,
Microsoft_event_prefix_length,
Microsoft_event_prefix | +|--|--|--|--| +| HCI_VS_MSFT_Read_Supported_Features | Chosen base code | Subcommand_opcode | Status,
Subcommand_opcode,
Supported_features,
Microsoft_event_prefix_length,
Microsoft_event_prefix | #### Command_parameters **Subcommand_opcode** (1 octet): -| Value | Parameter description | -|---|---| -|0x00 | The subcommand opcode for [HCI_VS_MSFT_Read_Supported_Features][ref_HCI_VS_MSFT_Read_Supported_Features].| +| Value | Parameter description | +|--|--| +| 0x00 | The subcommand opcode for [HCI_VS_MSFT_Read_Supported_Features][ref_HCI_VS_MSFT_Read_Supported_Features]. | #### Return_parameters **Status** (1 octet): -| Value | Parameter description | -|---|---| -| 0x00 | The command succeeded. | -| 0x01 to 0xFF | The command failed. See _Error Codes_ in the Bluetooth Core specification for details. | +| Value | Parameter description | +|--|--| +| 0x00 | The command succeeded. | +| 0x01 to 0xFF | The command failed. See *Error Codes* in the Bluetooth Core specification for details. | **Subcommand_opcode** (1 octet): -| Value | Parameter description | -|---|---| -|0x00 | The subcommand opcode for [HCI_VS_MSFT_Read_Supported_Features][ref_HCI_VS_MSFT_Read_Supported_Features].| +| Value | Parameter description | +|--|--| +| 0x00 | The subcommand opcode for [HCI_VS_MSFT_Read_Supported_Features][ref_HCI_VS_MSFT_Read_Supported_Features]. | **Supported_features** (8 octets): -| Value | Parameter description | -|---|---| -|0x00000000 00000001 |Controller supports the RSSI Monitoring feature for BR/EDR connections. In addition, the controller supports [HCI_VS_MSFT_Read_Absolute_RSSI][ref_HCI_VS_MSFT_Read_Absolute_RSSI] to read the absolute RSSI metric of a BR/EDR connection. | -|0x00000000 00000002 |Controller supports the RSSI Monitoring feature for LE connections. | -|0x00000000 00000004 |Controller supports the RSSI Monitoring of LE legacy advertisements. | -|0x00000000 00000008|Controller supports Advertising Monitoring of LE legacy advertisements.| -|0x00000000 00000010 |Controller supports verifying the validity of the public X and Y coordinates on the curve during the Secure Simple pairing process for P-192 and P-256.
For more information, see [Bluetooth Core Specification Erratum 10734](https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=447440).| -|0x00000000 00000020|Controller supports Continuous Advertising Monitoring of LE legacy advertisements performed concurrently with other radio activities.| -|0x00000000 00000040|Reserved.| -|0x00000000 00000080|Reserved.| -|0x00000000 00000100|Reserved.| -|0xFFFFFFFF FFFFFFF0|Bits reserved for future definition. Must be zero.| +| Value | Parameter description | +|--|--| +| 0x00000000 00000001 | Controller supports the RSSI Monitoring feature for BR/EDR connections. In addition, the controller supports [HCI_VS_MSFT_Read_Absolute_RSSI][ref_HCI_VS_MSFT_Read_Absolute_RSSI] to read the absolute RSSI metric of a BR/EDR connection. | +| 0x00000000 00000002 | Controller supports the RSSI Monitoring feature for LE connections. | +| 0x00000000 00000004 | Controller supports the RSSI Monitoring of LE legacy advertisements. | +| 0x00000000 00000008 | Controller supports Advertising Monitoring of LE legacy advertisements. | +| 0x00000000 00000010 | Controller supports verifying the validity of the public X and Y coordinates on the curve during the Secure Simple pairing process for P-192 and P-256.
For more information, see [Bluetooth Core Specification Erratum 10734](https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=447440). | +| 0x00000000 00000020 | Controller supports Continuous Advertising Monitoring of LE advertisements performed concurrently with other radio activities, using [HCI_VS_MSFT_LE_Monitor_Advertisement [v1]][ref_HCI_VS_MSFT_LE_Monitor_Advertisement]. | +| 0x00000000 00000040 | Reserved. | +| 0x00000000 00000080 | Reserved. | +| 0x00000000 00000100 | Reserved. | +| 0x00000000 00000200 | Reserved. | +| 0x00000000 00000400 | Controller supports [HCI_VS_MSFT_LE_Monitor_Advertisement [v2]][ref_HCI_VS_MSFT_LE_Monitor_Advertisement]. Additionally, the Controller supports Continuous Advertising Monitoring of LE advertisements performed concurrently with other radio activities, using [HCI_VS_MSFT_LE_Monitor_Advertisement [v2]][ref_HCI_VS_MSFT_LE_Monitor_Advertisement]. | +| 0xFFFFFFFF FFFFF800 | Bits reserved for future definition. Must be zero. | **Microsoft_event_prefix_length** (1 octet): -| Value | Parameter description | -|---|---| -|0x00 to 0x20|Number of bytes in the Microsoft event prefix field as specified in the returned _Microsoft_event_prefix_. This is the number of bytes of constant information at the beginning of every Microsoft-specified HCI event.| +| Value | Parameter description | +|--|--| +| 0x00 to 0x20 | Number of bytes in the Microsoft event prefix field as specified in the returned *Microsoft_event_prefix*. This is the number of bytes of constant information at the beginning of every Microsoft-specified HCI event. | **Microsoft_event_prefix** (variable length): -| Value | Parameter description | -|---|---| -|Event prefix value| The constant information to expect at the beginning of each Microsoft-defined event. This information is used to distinguish Microsoft-defined events from other custom events.| +| Value | Parameter description | +|--|--| +| Event prefix value | The constant information to expect at the beginning of each Microsoft-defined event. This information is used to distinguish Microsoft-defined events from other custom events. | ### HCI_VS_MSFT_Monitor_Rssi @@ -123,134 +125,134 @@ The controller shall always complete this command promptly with a Command Comple HCI_VS_MSFT_Monitor_Rssi requests that the controller starts monitoring the measured link RSSI for a specified connection, and generates an event when the connection's measured link RSSI goes outside of the specified bounds. -|Command|Code|Command parameters|Return parameters| -|---|---|---|---| -|HCI_VS_MSFT_Monitor_Rssi|Chosen base code |Subcommand_opcode,
Connection_Handle,
RSSI_threshold_high,
RSSI_threshold_low,
RSSI_threshold_low_time_interval,
RSSI_sampling_period|Status,
Subcommand_opcode| +| Command | Code | Command parameters | Return parameters | +|--|--|--|--| +| HCI_VS_MSFT_Monitor_Rssi | Chosen base code | Subcommand_opcode,
Connection_Handle,
RSSI_threshold_high,
RSSI_threshold_low,
RSSI_threshold_low_time_interval,
RSSI_sampling_period | Status,
Subcommand_opcode | + +The controller shall notify the host of the RSSI value with a periodically generated event (based on the *RSSI_sampling_period*). The measured link RSSI shall be the **absolute** receiver signal strength value in dBm for the BR/EDR connection. -The controller shall notify the host of the RSSI value with a periodically generated event (based on the _RSSI_sampling_period_). The measured link RSSI shall be the **absolute** receiver signal strength value in dBm for the BR/EDR connection. +In response to a HCI_VS_MSFT_Monitor_Rssi command, the controller shall generate a Command Complete event with status equaling zero if the controller can begin monitoring, or a nonzero status otherwise. If the status value is nonzero, the controller shall not generate an [HCI_VS_MSFT_Rssi_Event][ref_HCI_VS_MSFT_Rssi_Event] in response to this command. -In response to a HCI_VS_MSFT_Monitor_Rssi command, the controller shall generate a Command Complete event with status equaling zero if the controller can begin monitoring, or a non-zero status otherwise. If the status value is non-zero, the controller shall not generate an [HCI_VS_MSFT_Rssi_Event][ref_HCI_VS_MSFT_Rssi_Event] in response to this command. +The controller shall refuse the command if another HCI_VS_MSFT_Monitor_Rssi command with the same *Connection_Handle* is outstanding, or if the specified connection handle is invalid. The controller may also refuse the command for other reasons, such as resource exhaustion. -The controller shall refuse the command if another HCI_VS_MSFT_Monitor_Rssi command with the same _Connection_Handle_ is outstanding, or if the specified connection handle is invalid. The controller may also refuse the command for other reasons, such as resource exhaustion. +This state diagram shows the transition states on the controller when monitoring RSSI for a connection. -This state diagram shows the transition states on the controller when monitoring RSSI for a connection.![State diagram of HCI_VS_MSFT_Monitor_Rssi](images/HCI_VS_MSFT_Monitor_Rssi_State_Diagram.png) +:::image type="content" source="images/HCI_VS_MSFT_Monitor_Rssi_State_Diagram.png" alt-text="State diagram of HCI_VS_MSFT_Monitor_Rssi"::: -The controller shall generate an [HCI_VS_MSFT_Rssi_Event][ref_HCI_VS_MSFT_Rssi_Event] when the received RSSI is greater than or equal to the specified _RSSI_threshold_high_. After this event has been generated, the controller shall not generate a new [HCI_VS_MSFT_Rssi_Event][ref_HCI_VS_MSFT_Rssi_Event] to specify that the _RSSI_threshold_high_ has been exceeded until it generates an [HCI_VS_MSFT_Rssi_Event][ref_HCI_VS_MSFT_Rssi_Event] that specifies the RSSI has fallen below _RSSI_threshold_low_. +The controller shall generate an [HCI_VS_MSFT_Rssi_Event][ref_HCI_VS_MSFT_Rssi_Event] when the received RSSI is greater than or equal to the specified *RSSI_threshold_high*. After this event has been generated, the controller shall not generate a new [HCI_VS_MSFT_Rssi_Event][ref_HCI_VS_MSFT_Rssi_Event] to specify that the *RSSI_threshold_high* has been exceeded until it generates an [HCI_VS_MSFT_Rssi_Event][ref_HCI_VS_MSFT_Rssi_Event] that specifies the RSSI has fallen below *RSSI_threshold_low*. -The controller shall generate an [HCI_VS_MSFT_Rssi_Event][ref_HCI_VS_MSFT_Rssi_Event] when the received RSSI equals or falls below the specified _RSSI_threshold_low_ over the specified _RSSI_threshold_low_time_interval_. After this event has been generated, the controller shall not generate a new [HCI_VS_MSFT_Rssi_Event][ref_HCI_VS_MSFT_Rssi_Event] to specify that the RSSI has fallen below the _RSSI_threshold_low_ until an [HCI_VS_MSFT_Rssi_Event][ref_HCI_VS_MSFT_Rssi_Event] event is generated to specify that _RSSI_threshold_high_ has been reached or exceeded. +The controller shall generate an [HCI_VS_MSFT_Rssi_Event][ref_HCI_VS_MSFT_Rssi_Event] when the received RSSI equals or falls below the specified *RSSI_threshold_low* over the specified *RSSI_threshold_low_time_interval*. After this event has been generated, the controller shall not generate a new [HCI_VS_MSFT_Rssi_Event][ref_HCI_VS_MSFT_Rssi_Event] to specify that the RSSI has fallen below the *RSSI_threshold_low* until an [HCI_VS_MSFT_Rssi_Event][ref_HCI_VS_MSFT_Rssi_Event] event is generated to specify that *RSSI_threshold_high* has been reached or exceeded. -If the _RSSI_sampling_period_ is between 0x01 and 0xFE, the controller shall generate an [HCI_VS_MSFT_Rssi_Event][ref_HCI_VS_MSFT_Rssi_Event] periodically every _RSSI_sampling_period_. This event shall contain the average of the RSSI calculated over the _RSSI_sampling_period_. -If the _RSSI_sampling_period_ is 0x00 or 0xFF, the controller shall **not** notify the host periodically with [HCI_VS_MSFT_Rssi_Event][ref_HCI_VS_MSFT_Rssi_Event]. +If the *RSSI_sampling_period* is between 0x01 and 0xFE, the controller shall generate an [HCI_VS_MSFT_Rssi_Event][ref_HCI_VS_MSFT_Rssi_Event] periodically every *RSSI_sampling_period*. This event shall contain the average of the RSSI calculated over the *RSSI_sampling_period*. +If the *RSSI_sampling_period* is 0x00 or 0xFF, the controller shall **not** notify the host periodically with [HCI_VS_MSFT_Rssi_Event][ref_HCI_VS_MSFT_Rssi_Event]. #### Command_parameters Subcommand_opcode (1 octet): -| Value | Parameter description | -|---|---| -|0x01 | The subcommand opcode for [HCI_VS_MSFT_Monitor_Rssi][ref_HCI_VS_MSFT_Monitor_Rssi].| +| Value | Parameter description | +|--|--| +| 0x01 | The subcommand opcode for [HCI_VS_MSFT_Monitor_Rssi][ref_HCI_VS_MSFT_Monitor_Rssi]. | Connection_Handle (2 octets): -| Value | Parameter description | -|---|---| -|0xXXXX | The handle for the connection whose RSSI must be monitored.| +| Value | Parameter description | +|--|--| +| 0xXXXX | The handle for the connection whose RSSI must be monitored. | RSSI_threshold_high (1 octet): -| Value | Parameter description | -|---|---| -| 0xXX | The maximum expected RSSI value. The controller will generate an event if the observed RSSI becomes greater than or equal to this value.
Unit: dBm
BR/EDR Range: -128 to 127 (signed integer)
LE Range: -127 to 20 (signed integer)| +| Value | Parameter description | +|--|--| +| 0xXX | The maximum expected RSSI value. The controller generates an event if the observed RSSI becomes greater than or equal to this value.
Unit: dBm
BR/EDR Range: -128 to 127 (signed integer)
LE Range: -127 to 20 (signed integer) | RSSI_threshold_low (1 octet): -| Value | Parameter description | -|---|---| -| 0xXX |The minimum expected RSSI value. The controller will generate an event if the observed RSSI becomes less than or equal to this value.
Unit: dBm
BR/EDR Mandatory Range: -128 to 127 (signed integer)
LE Mandatory Range: -127 to 20 (signed integer)| +| Value | Parameter description | +|--|--| +| 0xXX | The minimum expected RSSI value. The controller generates an event if the observed RSSI becomes less than or equal to this value.
Unit: dBm
BR/EDR Mandatory Range: -128 to 127 (signed integer)
LE Mandatory Range: -127 to 20 (signed integer) | RSSI_threshold_low_time_interval (1 octet): -| Value | Parameter description | -|---|---| -|0x00|Reserved value.| -|_N_ = 0xXX|The time in seconds over which the RSSI value should be below _RSSI_threshold_low_ before an [HCI_VS_MSFT_Rssi_Event][ref_HCI_VS_MSFT_Rssi_Event] is generated.
Time period = _N_ * 1 second
Mandatory Range: 0x01 to 0x3C| +| Value | Parameter description | +|--|--| +| 0x00 | Reserved value. | +| *N* = 0xXX | The time in seconds over which the RSSI value should be below *RSSI_threshold_low* before an [HCI_VS_MSFT_Rssi_Event][ref_HCI_VS_MSFT_Rssi_Event] is generated.
Time period = *N* * 1 second
Mandatory Range: 0x01 to 0x3C | RSSI_sampling_period (1 octet): -| Value | Parameter description | -|---|---| -|0x00|Reserved value.| -|_N_ = 0xXX|The sampling interval in milliseconds.
Time period = _N_ * 100 milliseconds
Mandatory Range: 0x01 to 0xFE| -|0xFF|Reserved value.| +| Value | Parameter description | +|--|--| +| 0x00 | Reserved value. | +| *N* = 0xXX | The sampling interval in milliseconds.
Time period = *N* * 100 milliseconds
Mandatory Range: 0x01 to 0xFE | +| 0xFF | Reserved value. | #### Return_parameters Status (1 octet): -| Value | Parameter description | -|---|---| -| 0x00 | The command succeeded. | -| 0x01 to 0xFF | The command failed. See _Error Codes_ in the Bluetooth Core specification for details. | -|0x07|The controller shall return _Memory Capacity Exceeded_ if it does not have enough memory to process the command.| -|_Error code_| The command failed. See _Error Codes_ in the Bluetooth Core specification for details.| +| Value | Parameter description | +|--|--| +| 0x00 | The command succeeded. | +| 0x01 to 0xFF | The command failed. See *Error Codes* in the Bluetooth Core specification for details. | +| 0x07 | The controller shall return *Memory Capacity Exceeded* if it doesn't have enough memory to process the command. | +| *Error code* | The command failed. See *Error Codes* in the Bluetooth Core specification for details. | Subcommand_opcode (1 octet): -| Value | Parameter description | -|---|---| -|0x01|The subcommand opcode for HCI_VS_MSFT_Monitor_Rssi.| +| Value | Parameter description | +|--|--| +| 0x01 | The subcommand opcode for HCI_VS_MSFT_Monitor_Rssi. | #### Events Generated Unless Masked Away -The controller shall promptly generate a Command Complete event when the [HCI_VS_MSFT_Monitor_Rssi][ref_HCI_VS_MSFT_Monitor_Rssi] command is received. If the Command Complete event returns a status of 0, the controller shall generate an [HCI_VS_MSFT_Rssi_Event][ref_HCI_VS_MSFT_Rssi_Event] when one of the following occurs. +The controller shall promptly generate a Command Complete event when the [HCI_VS_MSFT_Monitor_Rssi][ref_HCI_VS_MSFT_Monitor_Rssi] command is received. If the Command Complete event returns a status of 0, the controller shall generate an [HCI_VS_MSFT_Rssi_Event][ref_HCI_VS_MSFT_Rssi_Event] when one of the following conditions occurs. -- The observed RSSI for the device over _RSSI_threshold_low_time_interval_ becomes equal to or less than the specified _RSSI_threshold_low_ value. +- The observed RSSI for the device over *RSSI_threshold_low_time_interval* becomes equal to or less than the specified *RSSI_threshold_low* value. +- The observed RSSI for the device becomes greater than or equal to the specified *RSSI_threshold_high* value. +- The *RSSI_sampling_period* is valid and the sampling period expires. -- The observed RSSI for the device becomes greater than or equal to the specified _RSSI_threshold_high_ value. - -- The _RSSI_sampling_period_ is valid and the sampling period expires. - -The controller should do all necessary cleanup if connectivity with the specified device is lost. In this case, an [HCI_VS_MSFT_Cancel_Monitor_Rssi][ref_HCI_VS_MSFT_Cancel_Monitor_Rssi] command is not sent to the controller. +The controller should do all necessary cleanup if connectivity with the specified device is lost. In this case, an [HCI_VS_MSFT_Cancel_Monitor_Rssi][ref_HCI_VS_MSFT_Cancel_Monitor_Rssi] command isn't sent to the controller. ### HCI_VS_MSFT_Cancel_Monitor_Rssi [ref_HCI_VS_MSFT_Cancel_Monitor_Rssi]: #hci_vs_msft_cancel_monitor_rssi -HCI_VS_MSFT_Cancel_Monitor_Rssi cancels a previously-issued [HCI_VS_MSFT_Monitor_Rssi][ref_HCI_VS_MSFT_Monitor_Rssi] command. +HCI_VS_MSFT_Cancel_Monitor_Rssi cancels a previously issued [HCI_VS_MSFT_Monitor_Rssi][ref_HCI_VS_MSFT_Monitor_Rssi] command. The controller shall promptly generate a Command Completed event in response to this command. -|Command|Code|Command parameters|Return parameters| -|---|---|---|---| -|HCI_VS_MSFT_Cancel_Monitor_Rssi|Chosen base code |Subcommand_opcode,
Connection_Handle|Status,
Subcommand_opcode| +| Command | Code | Command parameters | Return parameters | +|--|--|--|--| +| HCI_VS_MSFT_Cancel_Monitor_Rssi | Chosen base code | Subcommand_opcode,
Connection_Handle | Status,
Subcommand_opcode | #### Command_parameters Subcommand_opcode (1 octet): -| Value | Parameter description | -|---|---| -|0x02 | The subcommand opcode for [HCI_VS_MSFT_Cancel_Monitor_Rssi][ref_HCI_VS_MSFT_Cancel_Monitor_Rssi].| +| Value | Parameter description | +|--|--| +| 0x02 | The subcommand opcode for [HCI_VS_MSFT_Cancel_Monitor_Rssi][ref_HCI_VS_MSFT_Cancel_Monitor_Rssi]. | -Connection_Handle (1 octets): +Connection_Handle (2 octets): -| Value | Parameter description | -|---|---| -|0xXXXX | The handle for the connection whose RSSI must be canceled.| +| Value | Parameter description | +|--|--| +| 0xXXXX | The handle for the connection whose RSSI must be canceled. | #### Return_parameters Status (1 octet): -| Value | Parameter description | -|---|---| -| 0x00 | The command succeeded. | -| 0x01 to 0xFF | The command failed. See _Error Codes_ in the Bluetooth Core specification for details. | +| Value | Parameter description | +|--|--| +| 0x00 | The command succeeded. | +| 0x01 to 0xFF | The command failed. See *Error Codes* in the Bluetooth Core specification for details. | Subcommand_opcode (1 octet): -| Value | Parameter description | -|---|---| -|0x02|The subcommand opcode for [HCI_VS_MSFT_Cancel_Monitor_Rssi][ref_HCI_VS_MSFT_Cancel_Monitor_Rssi].| +| Value | Parameter description | +|--|--| +| 0x02 | The subcommand opcode for [HCI_VS_MSFT_Cancel_Monitor_Rssi][ref_HCI_VS_MSFT_Cancel_Monitor_Rssi]. | #### Events Generated Unless Masked Away @@ -267,198 +269,321 @@ HCI_VS_MSFT_LE_Monitor_Advertisement requests that the controller starts monitor - A specified Identity Resolution Key (IRK) can be used to resolve the private address of the device from which the advertisement packet originated. - A specified Bluetooth Address can be matched to the received advertisement packet. -|Command|Code|Command parameters|Return parameters| -|---|---|---|---| -|HCI_VS_MSFT_LE_Monitor_Advertisement|Chosen base code |Subcommand_opcode,
RSSI_threshold_high,
RSSI_threshold_low,
RSSI_threshold_low_time_interval,
RSSI_sampling_period,
Condition_type,
\|Status,
Subcommand_opcodee,
Monitor_Handle| +The v2 command permits the Host to combine some of the above conditions with options governing the source of the advertisement and the target of a directed advertisement, to further refine which advertisements are monitored. The v2 command also permits the Host to filter which monitored advertisements cause the Controller to generate advertisement reports. + +| Command | Code | Command parameters | Return parameters | +|--|--|--|--| +| HCI_VS_MSFT_LE_Monitor_Advertisement [v2] | Chosen base code | Subcommand_opcode_v2,
RSSI_threshold_high,
RSSI_threshold_low,
RSSI_threshold_low_time_interval,
RSSI_sampling_period,
Monitor_options,
Advertisement_report_filtering_options,
Peer_device_address,
Peer_device_address_type,
Peer_device_IRK,
Condition_type,
\ | Status,
Subcommand_opcode,
Monitor_Handle | +| HCI_VS_MSFT_LE_Monitor_Advertisement [v1] | Chosen base code | Subcommand_opcode_v1,
RSSI_threshold_high,
RSSI_threshold_low,
RSSI_threshold_low_time_interval,
RSSI_sampling_period,
Condition_type,
\ | Status,
Subcommand_opcode,
Monitor_Handle | -The controller shall generate a Command Complete event in response to this command. The status value should be set to zero if the controller can begin monitoring, or a non-zero status otherwise. -If the controller does not support RSSI monitoring for LE Advertisements, it shall ignore the _RSSI_threshold_high_, _RSSI_threshold_low_, _RSSI_threshold_low_time_interval_, and _RSSI_sampling_period_ parameter values. +The controller shall generate a Command Complete event in response to this command. The status value should be set to zero if the controller can begin monitoring, or a nonzero status otherwise. +If the controller doesn't support RSSI monitoring for LE Advertisements, it shall ignore the *RSSI_threshold_high*, *RSSI_threshold_low*, *RSSI_threshold_low_time_interval*, and *RSSI_sampling_period* parameter values. This state diagram shows the transition states on the controller when monitoring RSSI for an advertisement. -![State diagram for HCI_VS_MSFT_LE_Monitor_Advertisement.](images/HCI_VS_MSFT_LE_Monitor_Advertisement_State_Diagram.png) +:::image type="content" source="images/HCI_VS_MSFT_LE_Monitor_Advertisement_State_Diagram.svg" alt-text="State diagram for HCI_VS_MSFT_LE_Monitor_Advertisement."::: -The controller shall propagate the first advertisement packet to the host only when the received RSSI is greater than or equal to _RSSI_threshold_high_ for a particular device. The controller shall generate an [HCI_VS_MSFT_LE_Monitor_Device_Event][ref_HCI_VS_MSFT_LE_Monitor_Device_Event] with _Monitor_state_ set to 1 and _Monitor_handle_ set to the handle for this _Condition_, to notify the host that the controller is monitoring this particular device for _Condition_. -The controller shall stop monitoring for _Condition_ if the RSSI of the received advertisements equals or falls below _RSSI_threshold_low_ over _RSSI_threshold_low_interval_ for the particular device. The controller shall generate an [HCI_VS_MSFT_LE_Monitor_Device_Event][ref_HCI_VS_MSFT_LE_Monitor_Device_Event] with _Monitor_state_ set to 0 to notify the host that the controller has stopped monitoring the particular device for the _Condition_. After the controller specifies the HCI_VS_MSFT_LE_Monitor_Device_Event with _Monitor_state_ set to 0, the controller shall not allow further advertisement packets to flow to the host for the device until the controller has notified the host that the RSSI for the particular device has risen to or above _RSSI_threshold_high_ for the particular device for the _Condition_. -Additionally, the controller shall generate an [HCI_VS_MSFT_LE_Monitor_Device_Event][ref_HCI_VS_MSFT_LE_Monitor_Device_Event] with _Monitor_state_ set to 0 to notify the host that the controller has stopped monitoring the device for the _Condition_ if the specified _RSSI_threshold_low_time_interval_ expires without receiving any advertising packets from the device. If the controller is monitoring a device for a particular condition, the following statements are true. +The controller shall begin monitoring an advertisement only when the received RSSI is greater than or equal to *RSSI_threshold_high* for a particular device and the *Monitor_options* match (see below). The controller shall generate an [HCI_VS_MSFT_LE_Monitor_Device_Event][ref_HCI_VS_MSFT_LE_Monitor_Device_Event] with *Monitor_state* set to 1 and *Monitor_handle* set to the handle for this *Condition*, to notify the host that the controller is monitoring this particular device for *Condition*. Additionally, the Controller shall propagate the first advertisement report of a monitored advertisement to the Host only when the *Advertisement_report_filter_options* match (see below). -If the controller supports the RSSI monitoring of LE extended advertisements without sampling, the controller shall propagate anonymous advertisement packets to the host if the RSSI value for the packet is greater than or equal to _RSSI_threshold_high_. Anonymous advertisements shall not be tracked and the [HCI_VS_MSFT_LE_Monitor_Device_Event][ref_HCI_VS_MSFT_LE_Monitor_Device_Event] event shall not be generated. +The *Monitor_options* for a filter are considered a match based on the following logic (in pseudocode): -| _RSSI_sampling_period_ | Legacy Advertisements | Extended Advertisements (Non-Anonymous) | Extended Advertisements (Anonymous)| -|---|---|---|---| -|0x00|The controller shall propagate all received advertisement packets to the host for the device for this _Condition_ unless the controller previously received an [HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable][ref_HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable] command with _Enable_ set to 0x00. The controller shall propagate an advertisement packet to the host even if the received RSSI is less than or equal to _RSSI_threshold_low_ as long as _RSSI_threshold_low_time_interval_ has not expired for the particular device for this _Condition_. The RSSI value of this advertisement packet shall be the RSSI value of the received advertisement. | If the controller supports the RSSI monitoring of LE extended advertisements without sampling, same behavior as _Legacy Advertisements_ column except that an advertisement packet is defined as all PDUs in the advertising chain. | If the controller supports the RSSI monitoring of LE extended advertisements without sampling, the controller shall propagate all received advertisement packets to the host for the device for this _Condition_ unless the controller previously received an [HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable][ref_HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable] command with _Enable_ set to 0x00. | -|0x01 to 0xFE| The controller shall propagate legacy advertisement packets to the host every _RSSI_sampling_period_ specified unless the controller previously received an [HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable][ref_HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable] command with _Enable_ set to 0x00. The RSSI value specified for the advertisement shall be the average of the RSSI value received during this sampling interval. If the controller does not receive an advertisement packet during the sampling period, it shall not propagate an advertisement to the host. It is possible that _RSSI_sampling_period_ is less than _RSSI_threshold_low_time_interval_ and all advertisements received during the _RSSI_sampling_period_ have RSSI below _RSSI_threshold_low_. The controller shall still propagate the advertisement with the average of the RSSI value received during this sampling interval. | If the controller supports the RSSI monitoring of LE extended advertisements without sampling, the controller shall behave as if the _RSSI_sampling_period_ was 0x00. | If the controller supports the RSSI monitoring of LE extended advertisements without sampling, the controller shall behave as if the _RSSI_sampling_period_ was 0x00. | -|0xFF|The controller shall not allow further advertisement packets to flow to the host for the device for the _Condition_ until the controller has notified the host that the particular device's RSSI has fallen below _RSSI_threshold_low_ for _RSSI_threshold_low_time_interval_ for the particular device for this _Condition_. This notification is done by generating an [HCI_VS_MSFT_LE_Monitor_Device_Event][ref_HCI_VS_MSFT_LE_Monitor_Device_Event] with _Monitor_state_ set to 0.|If the controller supports the RSSI monitoring of LE extended advertisements without sampling, same behavior as _Legacy Advertisements_ column.| If the controller supports the RSSI monitoring of LE extended advertisements without sampling, the controller shall behave as if the _RSSI_sampling_period_ was 0x00. | +``` +MatchesCondition = (PDU Matches Condition Parameters) + +IsAdvAMatch = ((Monitor_options bit 0 is set) && ((AdvA == Peer_device_address) && (TxAdd == Peer_device_address_type))) || + ((Monitor_options bit 1 is set) && (AdvA resolvable with Peer_device_IRK)) + +IsDirectedAdvAMatch = (TargetA is permitted based on the Scanning Filter Policy) && + (((Monitor_options bit 2 is set) && ((AdvA == Peer_device_address) && (TxAdd == Peer_device_address_type))) || + ((Monitor_options bit 3 is set) && (AdvA resolvable with Peer_device_IRK))) -If the controller previously received an [HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable][ref_HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable] command with _Enable_ set to 0x00, the sampling period timer shall not be stopped. See Example: HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable on filters with sampling period for more information. -If the controller receives non-duplicate advertisement packets from the same device, it shall match each advertisement packet against the Conditions stored on the controller. +IsDirectedTargetAMatch = (Monitor_options bit 4 is set) && + (TargetA is permitted based on the Scanning Filter Policy) -If the controller receives an advertisement packet from a device that matches multiple Conditions, then the controller shall generate an [HCI_VS_MSFT_LE_Monitor_Device_Event][ref_HCI_VS_MSFT_LE_Monitor_Device_Event] for each _Condition_ that matched, with _Monitor_handle_ set to the _Condition_ that matched. +MonitorOptionsMatch = (MatchesCondition && IsAdvAMatch) || + IsDirectedAdvAMatch || + IsDirectedTargetAMatch || + ((Monitor_options bit 5 is set) && MatchesCondition) +``` + +And for a monitored advertisement, the *Advertisement_report_filter_options* are considered a match based on the following logic (in pseudocode): -If the controller is unable to monitor the RSSI values for all devices in range that match the _Condition_, it will keep monitoring as many devices as it can. The decision on what devices should be monitored will depend on the RSSI values of the received advertisements. The controller shall monitor devices with the greater received signal strength. +``` +IsDuplicateFilterSatisfied = (Advertisement_report_filter_options bit 0 is NOT set || PDU is not a duplicate) -If the controller has notified the host about a particular device (_A_) and it is monitoring devices at maximum hardware capacity, and if another device (_B_) comes into range with a higher RSSI value, then the controller shall notify the host that it has stopped monitoring the device (_A_) by generating an [HCI_VS_MSFT_LE_Monitor_Device_Event][ref_HCI_VS_MSFT_LE_Monitor_Device_Event] with _Monitor_state_ set to 0. The controller shall also generate an HCI_VS_MSFT_LE_Monitor_Device_Event with _Monitor_state_ set to 1 to notify the host that the device (_B_) is now being monitored. +ShouldGenerateLegacyReport = (Advertisement_report_filter_options bit 1 is set) && + (PDU is Legacy) && + MonitorOptionsMatch + +ShouldGenerateExtendedReport = (Advertisement_report_filter_options bit 2 is set) && + (PDU is Extended) && + MonitorOptionsMatch + +ShouldGenerateDirectedReport = (Advertisement_report_filter_options bit 3 is set) && + (PDU is Directed) && + MonitorOptionsMatch + +AdvertisementReportFilterOptionsMatch = IsDuplicateFilterSatisfied && + (ShouldGenerateLegacyReport || ShouldGenerateExtendedReport || ShouldGenerateDirectedReport) +``` + +The controller shall stop monitoring for *Condition* if the RSSI of the received advertisements equals or falls below *RSSI_threshold_low* over *RSSI_threshold_low_interval* for the particular device. The controller shall generate an [HCI_VS_MSFT_LE_Monitor_Device_Event][ref_HCI_VS_MSFT_LE_Monitor_Device_Event] with *Monitor_state* set to 0 to notify the host that the controller has stopped monitoring the particular device for the *Condition*. After the controller specifies the HCI_VS_MSFT_LE_Monitor_Device_Event with *Monitor_state* set to 0, the controller shall not allow further advertisement packets to flow to the host for the device until the controller has notified the host that the RSSI for the particular device has risen to or above *RSSI_threshold_high* for the particular device for the *Condition*. + +Additionally, the controller shall generate an [HCI_VS_MSFT_LE_Monitor_Device_Event][ref_HCI_VS_MSFT_LE_Monitor_Device_Event] with *Monitor_state* set to 0 to notify the host that the controller has stopped monitoring the device for the *Condition* if the specified *RSSI_threshold_low_time_interval* expires without receiving any advertising packets from the device. If the controller is monitoring a device for a particular condition, the following statements are true. + +If the controller supports the RSSI monitoring of LE extended advertisements without sampling, the controller shall propagate anonymous advertisement packets to the host if the RSSI value for the packet is greater than or equal to *RSSI_threshold_high*. Anonymous advertisements shall not be tracked and the [HCI_VS_MSFT_LE_Monitor_Device_Event][ref_HCI_VS_MSFT_LE_Monitor_Device_Event] event shall not be generated. + +If the controller supports the RSSI monitoring of LE advertisements without sampling, the controller shall generate a truncated advertising report in the case where the received fragment(s) of the advertisement are matching, but where the entire advertisement was not received successfully. + +The Controller shall support a minimum of 30 simultaneous Monitor_handles, a minimum of 30 simultaneous tracked devices, and a minimum of 20 simultaneous tracked duplicate advertisements. The Controller shall also be capable of performing a continuous LE scan at 10% duty cycle. + +If Address Resolution is enabled in the Controller and the Host intends to monitor a remote device with its IRK successfully stored in the Controller's resolving list, then the Host shall provide the Peer_Identity_Address and Peer_Identity_Address_Type parameters from the remote device’s resolving list entry as the Peer_device_address and Peer_device_address_type parameters, respectively. + +| *RSSI_sampling_period* | Legacy Advertisements | Extended Advertisements (Non-Anonymous) | Extended Advertisements (Anonymous) | +|--|--|--|--| +| 0x00 | The controller shall propagate all received advertisement packets to the host for the device for this *Condition* unless the controller previously received an [HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable][ref_HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable] command with *Enable* set to 0x00. The controller shall propagate an advertisement packet to the host even if the received RSSI is less than or equal to *RSSI_threshold_low* as long as *RSSI_threshold_low_time_interval* hasn't expired for the particular device for this *Condition*. The RSSI value of this advertisement packet shall be the RSSI value of the received advertisement. | If the controller supports the RSSI monitoring of LE extended advertisements without sampling, same behavior as *Legacy Advertisements* column except that an advertisement packet is defined as all PDUs in the advertising chain. | If the controller supports the RSSI monitoring of LE extended advertisements without sampling, the controller shall propagate all received advertisement packets to the host for the device for this *Condition* unless the controller previously received an [HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable][ref_HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable] command with *Enable* set to 0x00. | +| 0x01 to 0xFE | The controller shall propagate legacy advertisement packets to the host every *RSSI_sampling_period* specified unless the controller previously received an [HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable][ref_HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable] command with *Enable* set to 0x00. The RSSI value specified for the advertisement shall be the average of the RSSI value received during this sampling interval. If the controller doesn't receive an advertisement packet during the sampling period, it shall not propagate an advertisement to the host. It's possible that *RSSI_sampling_period* is less than *RSSI_threshold_low_time_interval* and all advertisements received during the *RSSI_sampling_period* have RSSI below *RSSI_threshold_low*. The controller shall still propagate the advertisement with the average of the RSSI value received during this sampling interval. | If the controller supports the RSSI monitoring of LE extended advertisements without sampling, the controller shall behave as if the *RSSI_sampling_period* was 0x00. | If the controller supports the RSSI monitoring of LE extended advertisements without sampling, the controller shall behave as if the *RSSI_sampling_period* was 0x00. | +| 0xFF | The controller shall not allow further advertisement packets to flow to the host for the device for the *Condition* until the controller has notified the host that the particular device's RSSI has fallen below *RSSI_threshold_low* for *RSSI_threshold_low_time_interval* for the particular device for this *Condition*. This notification is done by generating an [HCI_VS_MSFT_LE_Monitor_Device_Event][ref_HCI_VS_MSFT_LE_Monitor_Device_Event] with *Monitor_state* set to 0. | If the controller supports the RSSI monitoring of LE extended advertisements without sampling, same behavior as *Legacy Advertisements* column. | If the controller supports the RSSI monitoring of LE extended advertisements without sampling, the controller shall behave as if the *RSSI_sampling_period* was 0x00. | + +If the controller previously received an [HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable][ref_HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable] command with *Enable* set to 0x00, the sampling period timer shall not be stopped. See Example: HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable on filters with sampling period for more information. +If the controller receives nonduplicate advertisement packets from the same device, it shall match each advertisement packet against the Conditions stored on the controller. + +If the controller receives an advertisement packet from a device that matches multiple Conditions, then the controller shall generate an [HCI_VS_MSFT_LE_Monitor_Device_Event][ref_HCI_VS_MSFT_LE_Monitor_Device_Event] for each *Condition* that matched, with *Monitor_handle* set to the *Condition* that matched. + +If the controller is unable to monitor the RSSI values for all devices in range that match the *Condition*, it keeps monitoring as many devices as it can. The decision on what devices should be monitored will depend on the RSSI values of the received advertisements. The controller shall monitor devices with the greater received signal strength. + +If the controller has notified the host about a particular device (*A*) and it's monitoring devices at maximum hardware capacity, and if another device (*B*) comes into range with a higher RSSI value, then the controller shall notify the host that it has stopped monitoring the device (*A*) by generating an [HCI_VS_MSFT_LE_Monitor_Device_Event][ref_HCI_VS_MSFT_LE_Monitor_Device_Event] with *Monitor_state* set to 0. The controller shall also generate an HCI_VS_MSFT_LE_Monitor_Device_Event with *Monitor_state* set to 1 to notify the host that the device (*B*) is now being monitored. #### Condition Type and Condition Parameters -The _Condition_type_ parameter specifies whether the _Condition_ parameter specifies a pattern, UUID, IRK, or BD_ADDR. +The *Condition_type* parameter specifies whether the *Condition* parameter specifies a pattern, UUID, IRK, or BD_ADDR. -If the _Condition_type_ parameter specifies a pattern, the _Condition_ contains 2 sections which contain the number of patterns present within the _Condition_, and the pattern data. +If the *Condition_type* parameter specifies a pattern, the *Condition* contains two sections that contain the number of patterns present within the *Condition*, and the pattern data. -![Pattern condition data layout](images/HCI_VS_MSFT_LE_Monitor_Advertisement_Conditions.png) +:::image type="content" source="images/HCI_VS_MSFT_LE_Monitor_Advertisement_Conditions.png" alt-text="Pattern condition data layout"::: -_Number of Patterns_ specifies the number of patterns that need to be matched. +*Number of Patterns* specifies the number of patterns that need to be matched. -_Pattern Data_ has the following format. +*Pattern Data* has the following format. -- _Length_ specifies the length of this pattern include the data type and start byte of the pattern. -- _AD Type_ specifies the AD Type field. -- _Start of Pattern_ specifies the starting byte position of the pattern immediately following AD Type. -- _Pattern_ has a size of (_Length_ - 0x2) and is the pattern to be matched for the specified AD Type within the advertisement packet from the specified starting byte. +- *Length* specifies the length of this pattern include the data type and start byte of the pattern. +- *AD Type* specifies the AD Type field. +- *Start of Pattern* specifies the starting byte position of the pattern immediately following AD Type. +- *Pattern* has a size of (*Length* - 0x2) and is the pattern to be matched for the specified AD Type within the advertisement packet from the specified starting byte. If there are multiple patterns specified, the controller shall ensure that at least one pattern matches the received advertisement. If the controller supports the RSSI monitoring of LE extended advertisements without sampling: -- The controller shall only look for the pattern in the first extended advertisement PDU. If the ad section extends beyond the first PDU, the controller shall look for the pattern within the part of the ad section that is in the first PDU. +- The controller shall look for the pattern in the first 251 octets of the Host Advertising Data and may look in any remaining octets of the Host Advertising Data. If the AD section extends beyond the first 251 octets of the Host Advertising Data, the controller shall look for the pattern within the part of the AD section that is in the first 251 octets of the Host Advertising Data and may look in any remaining octets of the Host Advertising Data. Note: based on fragmentation by the advertiser, the first 251 octets of the Host Advertising Data may extend across the AdvData of multiple advertising PDUs. Scanners should take care to limit the number of AuxPtrs that they follow, to avoid following excessively long chains of PDUs. - The controller shall track based on a per device address per advertising set basis. The controller shall propagate a [HCI_VS_MSFT_LE_Monitor_Device_Event][ref_HCI_VS_MSFT_LE_Monitor_Device_Event] for each advertising set that matches the pattern even if the advertisement comes from the same device address. -If the _Condition_type_ parameter specifies a UUID, the _Condition_ parameter contains a UUID Type and a UUID. The UUID Type specifies whether the UUID is 16-bit, 32-bit, or 128-bit. The controller shall parse the Service UUID of the advertisement packet to check for the specified UUID. If UUID Type is defined as 0x01, the controller shall parse the Incomplete List of 16-bit service UUIDs and complete list of 16-bit service UUIDs specified in the Service UUID AD Type. If the UUID Type is defined as 0x02, the controller shall parse the Incomplete List of 32-bit service UUIDs and complete list of 32-bit UUIDs specified in the Service UUID AD Type. If the UUID Type specified is 0x03, the controller shall parse the Incomplete List of 128-bit Service UUIDs and complete list of 128-bit Service UUIDs specified in the Service UUID AD Type. +If the *Condition_type* parameter specifies a UUID, the *Condition* parameter contains a UUID Type and a UUID. The UUID Type specifies whether the UUID is 16-bit, 32-bit, or 128-bit. The controller shall parse the Service UUID of the advertisement packet to check for the specified UUID. If UUID Type is defined as 0x01, the controller shall parse the Incomplete List of 16-bit service UUIDs and complete list of 16-bit service UUIDs specified in the Service UUID AD Type. If the UUID Type is defined as 0x02, the controller shall parse the Incomplete List of 32-bit service UUIDs and complete list of 32-bit UUIDs specified in the Service UUID AD Type. If the UUID Type specified is 0x03, the controller shall parse the Incomplete List of 128-bit Service UUIDs and complete list of 128-bit Service UUIDs specified in the Service UUID AD Type. If the controller supports the RSSI monitoring of LE extended advertisements without sampling: -- The controller shall only look for the Service UUID in the first extended advertisement PDU. If the ad section extends beyond the first PDU, the controller shall look for the Service UUID within the part of the ad section that is in the first PDU. +- The controller shall look for the Service UUID in the first 251 octets of the Host Advertising Data and may look in any remaining octets of the Host Advertising Data. If the AD section extends beyond the first 251 octets of the Host Advertising Data, the controller shall look for the Service UUID within the part of the AD section that is in the first 251 octets of the Host Advertising Data and may look in any remaining octets of the Host Advertising Data. Note: based on fragmentation by the advertiser, the first 251 octets of the Host Advertising Data may span the AdvData of multiple advertising PDUs. Scanners should take care to limit the number of AuxPtrs that they follow, to avoid following excessively long chains of PDUs. - The controller shall track based on a per device address per advertising set basis. The controller shall propagate a [HCI_VS_MSFT_LE_Monitor_Device_Event][ref_HCI_VS_MSFT_LE_Monitor_Device_Event] for each advertising set that matches the Service UUID even if the advertisement comes from the same device. -If the _Condition_type_ parameter specifies an IRK, the _Condition_ parameter contains the IRK. +If the *Condition_type* parameter specifies an IRK, the *Condition* parameter contains the IRK. -If the _Condition_type_ parameter specifies a Bluetooth Address, the _Condition_ parameter contains the address type and BD_ADDR. +If the *Condition_type* parameter specifies a Bluetooth Address, the *Condition* parameter contains the address type and BD_ADDR. The controller shall keep monitoring based on the conditions, even when scanning (Active or Passive) is enabled. When active scanning is enabled, the scan response for an advertisement matching a filter shall be propagated to the host. -If the controller receives a HCI_VS_MSFT_LE_Monitor_Advertisement command when the filters are disabled (due to a previously received [HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable][ref_HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable] command with _Enable_ set to 0x00), the controller shall accept the command if it can, but set it to a disabled state. +If the controller receives a HCI_VS_MSFT_LE_Monitor_Advertisement command when the filters are disabled (due to a previously received [HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable][ref_HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable] command with *Enable* set to 0x00), the controller shall accept the command if it can, but set it to a disabled state. The controller may also refuse the command for other reasons such as resource exhaustion. +If all bits of Monitor_options are clear, the Controller should return the error code _Invalid HCI Command Parameters_ (0x12). + +If bit 1 or bit 3 of Monitor_options is set and Peer_device_IRK is set to an invalid IRK, or none of the bits of Monitor_options is set, the Controller should return the error code _Invalid HCI Command Parameters_ (0x12). + +If bit 0 or bit 1 or bit 2 or bit 3 of Monitor_options is set and Condition_type is set to 0x03 or 0x04, then the Controller should return the error code _Invalid HCI Command Parameters_ (0x12). + +If bit 0 of Advertisement_report_filter_options is set and RSSI_sampling_period is any value other than 0x00, the Controller should return the error code _Invalid HCI Command Parameters_ (0x12). + +#### Missing parameters + +When a version of this command is issued that does not include all the parameters, the following shall be used: + +| Parameter | Value | +|--|--| +| Monitor_options | Bit 5 set; all other bits cleared | +| Advertisement_report_filter_options | Bits 1 and 2 set; all other bits cleared | +| Peer_device_IRK | 0x0000000000000000 0000000000000000 | +| Peer_device_address | 0x000000000000 | +| Peer_device_address_type | 0x00 | + #### Command_parameters -Subcommand_opcode (1 octet): +Subcommand_opcode_v1 (1 octet): + +| Value | Parameter description | +|--|--| +| 0x03 | The subcommand opcode for [HCI_VS_MSFT_LE_Monitor_Advertisement [v1]][ref_HCI_VS_MSFT_LE_Monitor_Advertisement]. | -| Value | Parameter description | -|---|---| -|0x03 | The subcommand opcode for [HCI_VS_MSFT_LE_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Monitor_Advertisement].| +Subcommand_opcode_v2 (1 octet): + +| Value | Parameter description | +|--|--| +| 0x0F | The subcommand opcode for [HCI_VS_MSFT_LE_Monitor_Advertisement [v2]][ref_HCI_VS_MSFT_LE_Monitor_Advertisement]. | RSSI_threshold_high (1 octet): -| Value | Parameter description | -|---|---| -|0xXX| The maximum expected RSSI value. The controller will generate an event if the observed RSSI becomes greater than or equal to this value.
Unit: dBm
Mandatory Range: -127 to 20 (signed integer)| +| Value | Parameter description | +|--|--| +| 0xXX | The maximum expected RSSI value. The controller generates an event if the observed RSSI becomes greater than or equal to this value.
Unit: dBm
Mandatory Range: -127 to 20 (signed integer) | RSSI_threshold_low (1 octet): -| Value | Parameter description | -|---|---| -|0xXX|The minimum expected RSSI value. The controller will generate an event if the observed RSSI becomes less than or equal to this value.
Unit: dBm
Mandatory Range: -127 to 20 (signed integer)| +| Value | Parameter description | +|--|--| +| 0xXX | The minimum expected RSSI value. The controller generates an event if the observed RSSI becomes less than or equal to this value.
Unit: dBm
Mandatory Range: -127 to 20 (signed integer) | RSSI_threshold_low_time_interval (1 octet): -| Value | Parameter description | -|---|---| -|0x00|Reserved value.| -|_N_ = 0xXX|The time in seconds over which the RSSI value should be below _RSSI_threshold_low_ before an [HCI_VS_MSFT_Rssi_Event][ref_HCI_VS_MSFT_Rssi_Event] is generated
Time period = _N_ * 1 second
Mandatory Range: 0x01 to 0x3C. +| Value | Parameter description | +|--|--| +| 0x00 | Reserved value. | +| *N* = 0xXX | The time in seconds over which the RSSI value should be below *RSSI_threshold_low* before an [HCI_VS_MSFT_Rssi_Event][ref_HCI_VS_MSFT_Rssi_Event] is generated
Time period = *N* * 1 second
Mandatory Range: 0x01 to 0x3C. | RSSI_sampling_period (1 octet): -| Value | Parameter description | -|---|---| -|0x00|The controller shall propagate all received advertisements to the host.| -|_N_ = 0xXX|The sampling interval in milliseconds.
Time period = _N_ * 100 milliseconds.
Mandatory Range: 0x01 to 0xFE| -|0xFF|The controller shall not propagate any of the received advertisements to the host.| +| Value | Parameter description | +|--|--| +| 0x00 | The controller shall propagate all received advertisements to the host. | +| *N* = 0xXX | The sampling interval in milliseconds.
Time period = *N* * 100 milliseconds.
Mandatory Range: 0x01 to 0xFE | +| 0xFF | The controller shall not propagate any of the received advertisements to the host. | + +Monitor_options (1 octet): + +| Bit number | Parameter description | +|--|--| +| 0 | The Controller shall monitor advertising PDUs where AdvA or its resolved Identity Address matches Peer_device_address and Peer_device_address_type and where TargetA is not present or, if it is present, the TargetA is permitted based on the Scanning Filter Policy, if those PDUs match the condition specified in Condition_Type. | +| 1 | The Controller shall monitor advertising PDUs where AdvA is resolvable with Peer_device_IRK and where TargetA is not present or, if it is present, the TargetA is permitted based on the Scanning Filter Policy, if those PDUs match the condition specified in Condition_Type. This bit shall not be set if Link Layer Privacy is in use in the Controller. | +| 2 | The Controller shall monitor directed advertising PDUs where the TargetA is permitted based on the Scanning Filter Policy and where AdvA or its resolved Identity Address matches Peer_device_address and Peer_device_address_type. This is regardless of whether the PDU matches the condition specified in Condition_Type. | +| 3 | The Controller shall monitor directed advertising PDUs where the TargetA is permitted based on the Scanning Filter Policy and where AdvA is resolvable with Peer_device_IRK. This is regardless of whether the PDU matches the condition specified in Condition_Type. This bit shall not be set if Link Layer Privacy is in use in the Controller. | +| 4 | The Controller shall monitor directed advertising PDUs where the TargetA is permitted based on the Scanning Filter Policy, regardless of the value of Peer_device_address and Peer_device_address_type or Peer_device_IRK and regardless of whether the PDU matches the condition specified in Condition_Type. | +| 5 | The Controller shall monitor advertising PDUs from any AdvA where TargetA is not present or, if it is present, the TargetA is permitted based on the Scanning Filter Policy, if those PDUs match the condition specified in Condition_Type. | +| All other bits | Reserved for future use | + +Advertisement_report_filtering_options (1 octet): + +| Bit number | Parameter description | +|--|--| +| 0 | Filter duplicate advertising PDUs. This bit shall only be set if RSSI_sampling_period is 0x00. | +| 1 | The Controller shall generate HCI_LE_Advertising_Report events or HCI_LE_Directed_Advertising_Report events or HCI_LE_Extended_Advertising_Report events for Legacy advertising PDUs, if those PDUs match the specified Monitor_options. | +| 2 | The Controller shall generate HCI_LE_Extended_Advertising_Report events for Extended advertising PDUs, if those PDUs match the specified Monitor_options. | +| 3 | The Controller shall generate HCI_LE_Advertising_Report events or HCI_LE_Directed_Advertising_Report events or HCI_LE_Extended_Advertising_Report events for directed advertising PDUs, if those PDUs match the specified Monitor_options. | +| All other bits | Reserved for future use | + +Peer_device_address (6 octets): + +| Value | Parameter description | +|--|--| +| 0xXXXXXXXXXXXX | Public Device Address or Random Device Address to match. | + +Peer_device_address_type (1 octet): + +| Value | Parameter description | +|--|--| +| 0x00 | Public Device Address | +| 0x01 | Random Device Address | +| All other values | Reserved for future use | + +Peer_device_IRK (16 octets): + +| Value | Parameter description | +|--|--| +| 0x0000000000000000 0000000000000000 | Invalid IRK. Shall not be the value when Monitor_options bit 1 is set or when Monitor_options bit 3 is set. | +| 0xXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX | IRK of the device to match. Peer_device_address and Peer_device_address_type shall be populated. | + Condition_type (1 octet): -| Value | Parameter description | -|---|---| -|0x01|The condition is a pattern that has to be matched on the advertisement.| -|0x02|The condition is a UUID Type and a UUID.| -|0x03|The condition is the resolution of an IRK.| -|0x04|The condition is a Bluetooth address Type and a Bluetooth address.| +| Value | Parameter description | +|--|--| +| 0x01 | The condition is a pattern that has to be matched on the advertisement. | +| 0x02 | The condition is a UUID Type and a UUID. | +| 0x03 | The condition is the resolution of an IRK. Excluded if any of Monitor_options bits 0, 1, 2, or 3 are set. | +| 0x04 | The condition is a Bluetooth address Type and a Bluetooth address. Excluded if any of Monitor_options bits 0, 1, 2, or 3 are set. | Condition: -The applicable fields for Condition depends on the value of Condition_type. See the Condition_type and Condition parameters section for more information. +The applicable fields for Condition depend on the value of Condition_type. See the Condition_type and Condition parameters section for more information. Number_of_patterns (1 octet): -|Value | Parameter description| -|---|---| -|0xXX| The number of patterns specified within the Pattern_data parameter.| +| Value | Parameter description | +|--|--| +| 0xXX | The number of patterns specified within the Pattern_data parameter. | Pattern_data (>3 octets): -|Value | Parameter description| -|---|---| -|Length|Length of this pattern.| -|Data type| Data Type of the advertisement section. The values are listed in the Bluetooth Assigned Numbers document.| -|Start byte| Starting position of the pattern to be matched for the specified Data Type.| -|Pattern| Pattern to be matched (size of Length – 0x2 bytes).| +| Value | Parameter description | +|--|--| +| Length | Length of this pattern. | +| Data type | Data Type of the advertisement section. The values are listed in the Bluetooth Assigned Numbers document. | +| Start byte | Starting position of the pattern to be matched for the specified Data Type. | +| Pattern | Pattern to be matched (size of Length – 0x2 bytes). | UUID_type (1 octet): -|Value | Parameter description| -|---|---| -|0x01| The UUID is a 16-bit service.| -|0x02| The UUID is a 32-bit service.| -|0x03| The UUID is a 128-bit service.| +| Value | Parameter description | +|--|--| +| 0x01 | The UUID is a 16-bit service. | +| 0x02 | The UUID is a 32-bit service. | +| 0x03 | The UUID is a 128-bit service. | UUID (2, 4, or 16 octets): -|Value | Parameter description| -|---|---| -|0xXXXX| 2 bytes if UUID_type is 0x01.
4 bytes if UUID_type is 0x02.
16 bytes if UUID_type is 0x03.| +| Value | Parameter description | +|--|--| +| 0xXXXX | 2 bytes if UUID_type is 0x01.
4 bytes if UUID_type is 0x02.
16 bytes if UUID_type is 0x03. | IRK (16 octets): -| Value | Parameter description | -|---|---| -|0xXXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX|The IRK to be used to resolve the private address.| +| Value | Parameter description | +|--|--| +| 0xXXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX | The IRK to be used to resolve the private address. | Address_type (1 octet): -| Value | Parameter description | -|---|---| -|0x00| Public Device Address.| -|0x01| Random Device Address.| -|0x02 to 0xFF| Reserved values for future use.| +| Value | Parameter description | +|--|--| +| 0x00 | Public Device Address. | +| 0x01 | Random Device Address. | +| 0x02 to 0xFF | Reserved values for future use. | BD_ADDR (6 octets): -| Value | Parameter description | -|---|---| -|0xXXXXXXXXXXXX|The Bluetooth address of the device to be monitored.| +| Value | Parameter description | +|--|--| +| 0xXXXXXXXXXXXX | The Bluetooth address of the device to be monitored. | #### Return_parameters Status (1 octet): -| Value | Parameter description | -|---|---| -| 0x00 | The command succeeded. | -|0x07|The controller shall return Memory Capacity Exceeded if it does not have enough memory to process the command.| -| Error code | The command failed. See _Error Codes_ in the Bluetooth Core specification for details. | +| Value | Parameter description | +|--|--| +| 0x00 | The command succeeded. | +| 0x07 | The controller shall return Memory Capacity Exceeded if it doesn't have enough memory to process the command. | +| Error code | The command failed. See *Error Codes* in the Bluetooth Core specification for details. | Subcommand_opcode (1 octet): -| Value | Parameter description | -|---|---| -|0x03| The subcommand opcode for [HCI_VS_MSFT_LE_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Monitor_Advertisement]. | +| Value | Parameter description | +|--|--| +| 0x03 or 0x0F | The subcommand opcode for [HCI_VS_MSFT_LE_Monitor_Advertisement [v1]][ref_HCI_VS_MSFT_LE_Monitor_Advertisement] or [HCI_VS_MSFT_LE_Monitor_Advertisement [v2]][ref_HCI_VS_MSFT_LE_Monitor_Advertisement], depending on which command was submitted. | Monitor_handle (1 octet): -| Value | Parameter description | -|---|---| -|0x00 to 0xFF|The handle to this rule. This handle is used as a parameter for [HCI_VS_MSFT_LE_Cancel_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Cancel_Monitor_Advertisement] to cancel monitoring the advertisement.
This parameter is only valid if Status is 0x00.| +| Value | Parameter description | +|--|--| +| 0x00 to 0xFF | The handle to this rule. This handle is used as a parameter for [HCI_VS_MSFT_LE_Cancel_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Cancel_Monitor_Advertisement] to cancel monitoring the advertisement.
This parameter is only valid if Status is 0x00. | #### Events Generated Unless Masked Away @@ -468,11 +593,11 @@ When the [HCI_VS_MSFT_LE_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Monitor_Adver [ref_HCI_VS_MSFT_LE_Cancel_Monitor_Advertisement]: #hci_vs_msft_le_cancel_monitor_advertisement -HCI_VS_MSFT_LE_Cancel_Monitor_Advertisement cancels a previously-issued [HCI_VS_MSFT_LE_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Monitor_Advertisement] command. +HCI_VS_MSFT_LE_Cancel_Monitor_Advertisement cancels a previously issued [HCI_VS_MSFT_LE_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Monitor_Advertisement] command. -|Command|Code|Command parameters|Return parameters| -|---|---|---|---| -|HCI_VS_MSFT_LE_Cancel_Monitor_Advertisement|Chosen base code |Subcommand_opcode,
Monitor_handle|Status,
Subcommand_opcode| +| Command | Code | Command parameters | Return parameters | +|--|--|--|--| +| HCI_VS_MSFT_LE_Cancel_Monitor_Advertisement | Chosen base code | Subcommand_opcode,
Monitor_handle | Status,
Subcommand_opcode | The controller shall promptly generate a Command Completed event in response to this command. @@ -480,31 +605,31 @@ The controller shall promptly generate a Command Completed event in response to Subcommand_opcode (1 octet): -| Value | Parameter description | -|---|---| -|0x04 | The subcommand opcode for [HCI_VS_MSFT_LE_Cancel_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Cancel_Monitor_Advertisement].| +| Value | Parameter description | +|--|--| +| 0x04 | The subcommand opcode for [HCI_VS_MSFT_LE_Cancel_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Cancel_Monitor_Advertisement]. | Connection_Handle (1 octet): -| Value | Parameter description | -|---|---| -|0xXX| The handle to the filter that is being cancelled.| +| Value | Parameter description | +|--|--| +| 0xXX | The handle to the filter that is being canceled. | #### Return_parameters Status (1 octet): -| Value | Parameter description | -|---|---| -| 0x00 | The command succeeded. | -|0x07|The controller shall return Memory Capacity Exceeded if it does not have enough memory to process the command.| -| Error code | The command failed. See _Error Codes_ in the Bluetooth Core specification for details. | +| Value | Parameter description | +|--|--| +| 0x00 | The command succeeded. | +| 0x07 | The controller shall return Memory Capacity Exceeded if it doesn't have enough memory to process the command. | +| Error code | The command failed. See *Error Codes* in the Bluetooth Core specification for details. | Subcommand_opcode (1 octet): -| Value | Parameter description | -|---|---| -|0x04| The subcommand opcode for [HCI_VS_MSFT_LE_Cancel_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Cancel_Monitor_Advertisement]. | +| Value | Parameter description | +|--|--| +| 0x04 | The subcommand opcode for [HCI_VS_MSFT_LE_Cancel_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Cancel_Monitor_Advertisement]. | #### Events Generated Unless Masked Away @@ -516,50 +641,50 @@ The controller shall generate a Command Complete event when the [HCI_VS_MSFT_LE_ HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable sets the state of the advertisement filters. -|Command|Code|Command parameters|Return parameters| -|---|---|---|---| -|HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable|Chosen base code |Subcommand_opcode,
Enable|Status,
Subcommand_opcode| +| Command | Code | Command parameters | Return parameters | +|--|--|--|--| +| HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable | Chosen base code | Subcommand_opcode,
Enable | Status,
Subcommand_opcode | -If _Enable_ is set to 0x00, the controller shall propagate received advertisements to the host based on existing filter accept list settings. The controller shall continue monitoring the devices that are currently being monitored and generate an [HCI_VS_MSFT_LE_Monitor_Device_Event][ref_HCI_VS_MSFT_LE_Monitor_Device_Event] with _Monitor_state_ set to 0 if the device is no longer being monitored. The controller shall generate an [HCI_VS_MSFT_LE_Monitor_Device_Event][ref_HCI_VS_MSFT_LE_Monitor_Device_Event] with _Monitor_state_ set to 1 if a new device is being monitored. The host may issue HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable with _Enable_ set to 0x01 to reenable all the filter conditions. +If *Enable* is set to 0x00, the controller shall propagate received advertisements to the host based on existing filter accept list settings. The controller shall continue monitoring the devices that are currently being monitored and generate an [HCI_VS_MSFT_LE_Monitor_Device_Event][ref_HCI_VS_MSFT_LE_Monitor_Device_Event] with *Monitor_state* set to 0 if the device is no longer being monitored. The controller shall generate an [HCI_VS_MSFT_LE_Monitor_Device_Event][ref_HCI_VS_MSFT_LE_Monitor_Device_Event] with *Monitor_state* set to 1 if a new device is being monitored. The host may issue HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable with *Enable* set to 0x01 to reenable all the filter conditions. -If _Enable_ is set to 0x01, this command enables all filters that were set with a previously-issued [HCI_VS_MSFT_LE_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Monitor_Advertisement] command. The controller shall reject an HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable command if it does not toggle the filter state: +If *Enable* is set to 0x01, this command enables all filters that were set with a previously issued [HCI_VS_MSFT_LE_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Monitor_Advertisement] command. The controller shall reject an HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable command if it doesn't toggle the filter state: -- The controller shall reject an HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable command with _Enable_ set to 0x01 if it previously received an HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable command with _Enable_ set to 0x01. -- The controller shall reject the HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable command with _Enable_ set to 0x00 if it previously received an HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable command with _Enable_ set to 0x00. +- The controller shall reject an HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable command with *Enable* set to 0x01 if it previously received an HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable command with *Enable* set to 0x01. +- The controller shall reject the HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable command with *Enable* set to 0x00 if it previously received an HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable command with *Enable* set to 0x00. -The default state of the advertisement filter shall be off. This state is equivalent to the controller previously receiving a HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable command with _Enable_ set to 0x00. +The default state of the advertisement filter shall be off. This state is equivalent to the controller previously receiving a HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable command with *Enable* set to 0x00. The controller shall promptly generate a Command Completed event in response to this command. #### Command_parameters Subcommand_opcode (1 octet): -| Value | Parameter description | -|---|---| -|0x05| The subcommand opcode for [HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable][ref_HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable].| +| Value | Parameter description | +|--|--| +| 0x05 | The subcommand opcode for [HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable][ref_HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable]. | Enable (1 octet): -| Value | Parameter description | -|---|---| -|0x00| Revert to current filter accept list behavior, but continue monitoring devices based on the _Condition_ from [HCI_VS_MSFT_LE_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Monitor_Advertisement] commands.| -|0x01|Enable all issued [HCI_VS_MSFT_LE_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Monitor_Advertisement] commands on the controller.| +| Value | Parameter description | +|--|--| +| 0x00 | Revert to current filter accept list behavior, but continue monitoring devices based on the *Condition* from [HCI_VS_MSFT_LE_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Monitor_Advertisement] commands. | +| 0x01 | Enable all issued [HCI_VS_MSFT_LE_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Monitor_Advertisement] commands on the controller. | #### Return_parameter Status (1 octet): -|Value|Parameter description| -|---|---| -|0x00|The command succeeded.| -|0x0C|The controller shall return _Command Disallowed_ if the controller rejected the command because it previously saw an [HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable][ref_HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable] command with _Enable_ set to the same value as this command.| -|Error code|The command failed. See _Error Codes_ in the Bluetooth Core specification for details.| +| Value | Parameter description | +|--|--| +| 0x00 | The command succeeded. | +| 0x0C | The controller shall return *Command Disallowed* if the controller rejected the command because it previously saw an [HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable][ref_HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable] command with *Enable* set to the same value as this command. | +| Error code | The command failed. See *Error Codes* in the Bluetooth Core specification for details. | Subcommand_opcode (1 octet): -|Value|Parameter description| -|---|---| -|0x05|The subcommand opcode for [HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable][ref_HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable].| +| Value | Parameter description | +|--|--| +| 0x05 | The subcommand opcode for [HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable][ref_HCI_VS_MSFT_LE_Set_Advertisement_Filter_Enable]. | #### Events Generated Unless Masked Away @@ -571,26 +696,26 @@ The controller shall generate a Command Complete event when the [HCI_VS_MSFT_LE_ HCI_VS_MSFT_Read_Absolute_RSSI reads the **absolute** Received Signal Strength Indication (RSSI) value for a BR/EDR connection from the controller. -|Command|Code|Command parameters|Return parameters| -|---|---|---|---| -|HCI_VS_MSFT_Read_Absolute_RSSI|Chosen base code |Subcommand_opcode,
Connection_Handle|Status,
Subcommand_opcode,
Connection_Handle,
RSSI| +| Command | Code | Command parameters | Return parameters | +|--|--|--|--| +| HCI_VS_MSFT_Read_Absolute_RSSI | Chosen base code | Subcommand_opcode,
Connection_Handle | Status,
Subcommand_opcode,
Connection_Handle,
RSSI | -A connection handle is provided as both a command and return parameter to identify the ACL connection whose RSSI is being read. The RSSI metric is the **absolute** receiver signal strength in dBm to ± 6 dB accuracy. If the RSSI cannot be read, the RSSI metric shall be set to 127. +A connection handle is provided as both a command and return parameter to identify the ACL connection whose RSSI is being read. The RSSI metric is the **absolute** receiver signal strength in dBm to ± 6 dB accuracy. If the RSSI can't be read, the RSSI metric shall be set to 127. The controller shall always complete this command promptly with a Command Completed event. #### Command_parameters Subcommand_opcode (1 octet): -| Value | Parameter description | -|---|---| -|0x06| The subcommand opcode for HCI_VS_MSFT_Read_Absolute_RSSI.| +| Value | Parameter description | +|--|--| +| 0x06 | The subcommand opcode for HCI_VS_MSFT_Read_Absolute_RSSI. | Connection_Handle (2 octets): -| Value | Parameter description | -|---|---| -|0xXXXX|The handle for the BR/EDR connection whose RSSI has to be read.| +| Value | Parameter description | +|--|--| +| 0xXXXX | The handle for the BR/EDR connection whose RSSI has to be read. | #### Return_parameters @@ -599,7 +724,7 @@ Status (1 octet): | Value | Parameter description | |--|--| | 0x00 | The command succeeded. | -| 0x01 to 0xFF | The command failed. See _Error Codes_ in the Bluetooth Core specification for details. | +| 0x01 to 0xFF | The command failed. See *Error Codes* in the Bluetooth Core specification for details. | Subcommand_opcode (1 octet): @@ -617,7 +742,7 @@ RSSI (1 octet): | Value | Parameter description | |--|--| -| N = 0xXX | The RSSI value for the BR/EDR connection.
Unit: dBm
Mandatory Range: -128 to 127 (signed integer) | +| N = 0xXX | The RSSI value for the BR/EDR connection.
Unit: dBm
Mandatory Range: -128 to 127 (signed integer) | #### Events Generated Unless Masked Away @@ -637,11 +762,11 @@ All Microsoft-defined Bluetooth HCI events are vendor-defined events and use eve [ref_HCI_VS_MSFT_RSSI_Event]: #hci_vs_msft_rssi_event HCI_VS_MSFT_RSSI_Event indicates that an [HCI_VS_MSFT_Monitor_Rssi][ref_HCI_VS_MSFT_Monitor_Rssi] command has completed. -If the _Status_ parameter is zero, the command completed because the RSSI value for the remote device changed to a value outside of the specified range. If the _Status_ parameter is non-zero, the command completed because the RSSI value of the connection can no longer be monitored. +If the *Status* parameter is zero, the command completed because the RSSI value for the remote device changed to a value outside of the specified range. If the *Status* parameter is nonzero, the command completed because the RSSI value of the connection can no longer be monitored. | Event | Event Code | Microsoft event code | Event parameters | |--|--|--|--| -| HCI_VS_MSFT_RSSI_Event | 0xFF | 0x01 | Event_prefix,
Microsoft_event_code,
Status,
Connection_Handle,
RSSI | +| HCI_VS_MSFT_RSSI_Event | 0xFF | 0x01 | Event_prefix,
Microsoft_event_code,
Status,
Connection_Handle,
RSSI | #### Event_parameters @@ -661,8 +786,8 @@ Status (1 octet): | Value | Parameter description | |--|--| -| 0x00 | Success. The RSSI value of the connection has met one of the following conditions. The RSSI reached or exceeded _RSSI_threshold_high_.
The RSSI reached or dropped below _RSSI_threshold_low_ over _RSSI_threshold_low_time_interval_ seconds.,
The _RSSI_sampling_period_ has expired and this event was generated to notify the host of the RSSI value. | -| 0x01 to 0xFF | Failure. The RSSI value of the connection can no longer be monitored. The error code is usually one of codes that describes why the underlying ACL connection was lost. | +| 0x00 | Success. The RSSI value of the connection has met one of the following conditions. The RSSI reached or exceeded *RSSI_threshold_high*.
The RSSI reached or dropped below *RSSI_threshold_low* over *RSSI_threshold_low_time_interval* seconds.
The *RSSI_sampling_period* has expired and this event was generated to notify the host of the RSSI value. | +| 0x01 to 0xFF | Failure. The RSSI value of the connection can no longer be monitored. The error code is usually one of codes that describes why the underlying ACL connection was lost. | Connection_Handle (2 octets): @@ -674,7 +799,7 @@ RSSI (1 octet): | Value | Parameter description | |--|--| -| 0xXX | The measured link RSSI value for the connection.
Unit: dBm
BR/EDR Range: -128 to 127 (signed integer)
LE Range: -127 to 20 (signed integer) | +| 0xXX | The measured link RSSI value for the connection.
Unit: dBm
BR/EDR Range: -128 to 127 (signed integer)
LE Range: -127 to 20 (signed integer) | ### HCI_VS_MSFT_LE_Monitor_Device_Event @@ -682,20 +807,20 @@ RSSI (1 octet): HCI_VS_MSFT_LE_Monitor_Device_Event indicates that the controller has either started or stopped monitoring a Bluetooth LE device. -If the _Monitor_state_ parameter value is 1, the controller started monitoring the Bluetooth device with the specified BD_ADDR. If the _Monitor_state_ parameter value is 0, the controller stopped monitoring the Bluetooth device with the specified BD_ADDR. +If the *Monitor_state* parameter value is 1, the controller started monitoring the Bluetooth device with the specified BD_ADDR. If the *Monitor_state* parameter value is 0, the controller stopped monitoring the Bluetooth device with the specified BD_ADDR. | Event | Event Code | Microsoft event code | Event parameters | -| --- | --- | --- | --- | -| HCI_VS_MSFT_LE_Monitor_Device_Event | 0xFF | 0x02 | Event_prefix,
Microsoft_event_code,
Address_type,
BD_ADDR,
Monitor_handle,
Monitor_state | +|--|--|--|--| +| HCI_VS_MSFT_LE_Monitor_Device_Event | 0xFF | 0x02 | Event_prefix,
Microsoft_event_code,
Address_type,
BD_ADDR,
Monitor_handle,
Monitor_state | -The controller shall not generate an HCI_VS_MSFT_LE_Monitor_Device_Event with the _Monitor_state_ parameter set to 0 if it has not already generated an HCI_VS_MSFT_LE_Monitor_Device_Event with _Monitor_state_ set to 1. +The controller shall not generate an HCI_VS_MSFT_LE_Monitor_Device_Event with the *Monitor_state* parameter set to 0 if it hasn't already generated an HCI_VS_MSFT_LE_Monitor_Device_Event with *Monitor_state* set to 1. #### Event_parameters Event_prefix (variable size): | Value | Parameter description | -| --- | --- | +|--|--| | Event prefix | The event prefix that flags this event as Microsoft-defined. The size and value are as returned by the [HCI_VS_MSFT_Read_Supported_Features][ref_HCI_VS_MSFT_Read_Supported_Features] command. | Microsoft_event_code (1 octet): @@ -710,7 +835,7 @@ Address_type (1 octet): |--|--| | 0x00 | Public Device Address. | | 0x01 | Random Device Address. | -| 0x02 to 0xFF | Reserved values for future use. | +| 0x02 to 0xFF | Reserved values for future use. | BD_ADDR (6 octets): @@ -728,8 +853,8 @@ Monitor_state (1 octet): | Value | Parameter description | |--|--| -| 0x00 | The controller stopped monitoring the device specified by _BD_ADDR_ and _Monitor_handle_. | -| 0x01 | The controller started monitoring the device specified by _BD_ADDR_ and _Monitor_handle_. | +| 0x00 | The controller stopped monitoring the device specified by *BD_ADDR* and *Monitor_handle*. | +| 0x01 | The controller started monitoring the device specified by *BD_ADDR* and *Monitor_handle*. | ## Appendix @@ -737,31 +862,31 @@ This section contains Microsoft-defined Bluetooth HCI extension examples and dia ### Example: Matching patterns for HCI_VS_MSFT_LE_Monitor_Advertisement -This example shows a received [HCI_VS_MSFT_LE_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Monitor_Advertisement] command and the evaluations of 3 different advertisement packets against the command parameters. +This example shows a received [HCI_VS_MSFT_LE_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Monitor_Advertisement] command and the evaluations of three different advertisement packets against the command parameters. Received [HCI_VS_MSFT_LE_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Monitor_Advertisement] command An [HCI_VS_MSFT_LE_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Monitor_Advertisement] command is received by the controller and contains the following parameters. -| Parameter | Value | Notes | -|------------------------------------|-------|--------------------------------------------------------------------------------------------------------| -| *Subcommand_opcode* | 0x03 | Subcommand opcode for [HCI_VS_MSFT_LE_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Monitor_Advertisement] | -| *RSSI_threshold_high* | 0x01 | 1dB | -| *RSSI_threshold_low* | 0xCE | -50dB | -| *RSSI_threshold_low_time_interval* | 0x05 | 5 seconds | -| *RSSI_sampling_period* | 0xFF | No sampling | -| *Condition_type* | 0x01 | Condition | -| *Condition* | 0x02 | 2 patterns should be matched | -| | 0x03 | Length of first pattern, including AD Type and starting position | -| | 0x01 | AD Type | -| | 0x00 | Starting position following the AD Type | -| | 0x01 | First pattern to be matched | -| | 0x06 | Length of second pattern, including AD Type and starting position | -| | 0xFF | AD Type (Manufacturer specific data) | -| | 0x00 | Starting position following the AD Type | -| | 0x00 | Second pattern to be matched | -| | 0x06 | | -| | 0xFF | | -| | 0xFF | | +| Parameter | Value | Notes | +|--|--|--| +| *Subcommand_opcode* | 0x03 | Subcommand opcode for [HCI_VS_MSFT_LE_Monitor_Advertisement][ref_HCI_VS_MSFT_LE_Monitor_Advertisement] | +| *RSSI_threshold_high* | 0x01 | 1dB | +| *RSSI_threshold_low* | 0xCE | -50dB | +| *RSSI_threshold_low_time_interval* | 0x05 | 5 seconds | +| *RSSI_sampling_period* | 0xFF | No sampling | +| *Condition_type* | 0x01 | Condition | +| *Condition* | 0x02 | Two patterns should be matched | +| | 0x03 | Length of first pattern, including AD Type and starting position | +| | 0x01 | AD Type | +| | 0x00 | Starting position following the AD Type | +| | 0x01 | First pattern to be matched | +| | 0x06 | Length of second pattern, including AD Type and starting position | +| | 0xFF | AD Type (Manufacturer specific data) | +| | 0x00 | Starting position following the AD Type | +| | 0x00 | Second pattern to be matched | +| | 0x06 | | +| | 0xFF | | +| | 0xFF | | The controller then receives the following advertisement packets. @@ -783,61 +908,61 @@ The controller then receives the following advertisement packets. #### Evaluating match for Advertisement packet [A] -| Description | Value | -|---------------------------------------------------------|-----------------------------------| -| AD Type of first pattern to be matched | 0x01 | -| Length of first pattern to be matched | 0x03 - 0x02 = 0x01 byte | -| Pattern to be matched at position 0x00 for AD Type 0x01 | 0x01 | -| Bytes at position 0x00 for the AD Type 0x01 | 0x01 _(MATCH!)_ | -| AD Type of second pattern to be matched | 0xFF (Manufacturer specific data) | -| Length of second pattern to be matched | 0x06 - 0x02 = 0x04 bytes | -| Pattern to be matched at position 0x00 for AD Type 0xFF | 0x00 0x06 0xFF 0xFF | -| Bytes at position 0x00 for the AD Type 0xFF | 0x00 0x06 0xFF 0xFF _(MATCH!)_ | +| Description | Value | +|--|--| +| AD Type of first pattern to be matched | 0x01 | +| Length of first pattern to be matched | 0x03 - 0x02 = 0x01 byte | +| Pattern to be matched at position 0x00 for AD Type 0x01 | 0x01 | +| Bytes at position 0x00 for the AD Type 0x01 | 0x01 *(MATCH!)* | +| AD Type of second pattern to be matched | 0xFF (Manufacturer specific data) | +| Length of second pattern to be matched | 0x06 - 0x02 = 0x04 bytes | +| Pattern to be matched at position 0x00 for AD Type 0xFF | 0x00 0x06 0xFF 0xFF | +| Bytes at position 0x00 for the AD Type 0xFF | 0x00 0x06 0xFF 0xFF *(MATCH!)* | Verdict: **PASS** (both patterns match) #### Evaluating match for Advertisement packet [B] -| Description | Value | -|---------------------------------------------------------|-----------------------------------| -| AD Type of first pattern to be matched | 0x01 | -| Length of first pattern to be matched | 0x03 - 0x02 = 0x01 byte | -| Pattern to be matched at position 0x00 for AD Type 0x01 | 0x01 | -| Bytes at position 0x00 for the AD Type 0x01 | 0x01 _(MATCH!)_ | -| AD Type of second pattern to be matched | 0xFF (Manufacturer specific data) | -| Length of second pattern to be matched | 0x06 - 0x02 = 0x04 bytes | -| Pattern to be matched at position 0x00 for AD Type 0xFF | 0x00 0x06 0xFF 0xFF | -| Bytes at position 0x00 for the AD Type 0xFF | 0x00 0x06 0xFF _(no match)_ | +| Description | Value | +|--|--| +| AD Type of first pattern to be matched | 0x01 | +| Length of first pattern to be matched | 0x03 - 0x02 = 0x01 byte | +| Pattern to be matched at position 0x00 for AD Type 0x01 | 0x01 | +| Bytes at position 0x00 for the AD Type 0x01 | 0x01 *(MATCH!)* | +| AD Type of second pattern to be matched | 0xFF (Manufacturer specific data) | +| Length of second pattern to be matched | 0x06 - 0x02 = 0x04 bytes | +| Pattern to be matched at position 0x00 for AD Type 0xFF | 0x00 0x06 0xFF 0xFF | +| Bytes at position 0x00 for the AD Type 0xFF | 0x00 0x06 0xFF *(no match)* | Verdict: **PASS** (only first pattern matches) -### Evaluating match for Advertisement packet [C] +#### Evaluating match for Advertisement packet [C] -| Description | Value | -|---------------------------------------------------------|--------------------------------------------------------------------| -| AD Type of first pattern to be matched | 0x01 | -| Length of first pattern to be matched | 0x03 - 0x02 = 0x01 byte | -| Pattern to be matched at position 0x00 for AD Type 0x01 | 0x01 | -| Bytes at position 0x00 for the AD Type 0x01 | Undefined. The advertisement does not have data with AD Type 0x01. | -| AD Type of second pattern to be matched | 0xFF (Manufacturer specific data) | -| Length of second pattern to be matched | 0x06 - 0x02 = 0x04 bytes | -| Pattern to be matched at position 0x00 for AD Type 0xFF | 0x00 0x06 0xFF 0xFF | -| Bytes at position 0x00 for the AD Type 0xFF | 0x00 0x06 0xFF 0xFF _(MATCH!)_ | +| Description | Value | +|--|--| +| AD Type of first pattern to be matched | 0x01 | +| Length of first pattern to be matched | 0x03 - 0x02 = 0x01 byte | +| Pattern to be matched at position 0x00 for AD Type 0x01 | 0x01 | +| Bytes at position 0x00 for the AD Type 0x01 | Undefined. The advertisement doesn't have data with AD Type 0x01. | +| AD Type of second pattern to be matched | 0xFF (Manufacturer specific data) | +| Length of second pattern to be matched | 0x06 - 0x02 = 0x04 bytes | +| Pattern to be matched at position 0x00 for AD Type 0xFF | 0x00 0x06 0xFF 0xFF | +| Bytes at position 0x00 for the AD Type 0xFF | 0x00 0x06 0xFF 0xFF *(MATCH!)* | Verdict: **PASS** (only second pattern matches) -### Evaluating match for Advertisement packet [D] +#### Evaluating match for Advertisement packet [D] -| Description | Value | -|---------------------------------------------------------|--------------------------------------------------------------------| -| AD Type of first pattern to be matched | 0x01 | -| Length of first pattern to be matched | 0x03 - 0x02 = 0x01 byte | -| Pattern to be matched at position 0x00 for AD Type 0x01 | 0x01 | -| Bytes at position 0x00 for the AD Type 0x01 | 0x02 _(no match)_ | -| AD Type of second pattern to be matched | 0xFF (Manufacturer specific data) | -| Length of second pattern to be matched | 0x06 - 0x02 = 0x04 bytes | -| Pattern to be matched at position 0x00 for AD Type 0xFF | 0x00 0x06 0xFF 0xFF | -| Bytes at position 0x00 for the AD Type 0xFF | 0x00 0x06 0xFF 0x01 _(no match)_ | +| Description | Value | +|--|--| +| AD Type of first pattern to be matched | 0x01 | +| Length of first pattern to be matched | 0x03 - 0x02 = 0x01 byte | +| Pattern to be matched at position 0x00 for AD Type 0x01 | 0x01 | +| Bytes at position 0x00 for the AD Type 0x01 | 0x02 *(no match)* | +| AD Type of second pattern to be matched | 0xFF (Manufacturer specific data) | +| Length of second pattern to be matched | 0x06 - 0x02 = 0x04 bytes | +| Pattern to be matched at position 0x00 for AD Type 0xFF | 0x00 0x06 0xFF 0xFF | +| Bytes at position 0x00 for the AD Type 0xFF | 0x00 0x06 0xFF 0x01 *(no match)* | Verdict: **FAIL** (neither pattern matches) @@ -846,33 +971,33 @@ Verdict: **FAIL** (neither pattern matches) This example illustrates RSSI advertisement monitoring. The RSSI values for received advertisements that matched a specified condition are shown below. | Time (s) | RSSI (dB) | -|----------|-----------| -| 1 | -100 | -| 2 | -90 | -| 3 | -5 | -| 4 | -15 | -| 5 | -30 | -| 6 | -15 | -| 7 | -45 | -| 8 | -20 | -| 9 | -35 | -| 10 | -45 | -| 11 | -70 | -| 12 | -85 | -| 13 | -85 | -| 14 | -85 | -| 15 | -90 | -| 16 | -90 | -| 17 | -70 | - -| Parameter | Value | -|------------------------------------|-----------| -| *RSSI_threshold_high* | -10dB | -| *RSSI_threshold_low* | -80dB | +|--|--| +| 1 | -100 | +| 2 | -90 | +| 3 | -5 | +| 4 | -15 | +| 5 | -30 | +| 6 | -15 | +| 7 | -45 | +| 8 | -20 | +| 9 | -35 | +| 10 | -45 | +| 11 | -70 | +| 12 | -85 | +| 13 | -85 | +| 14 | -85 | +| 15 | -90 | +| 16 | -90 | +| 17 | -70 | + +| Parameter | Value | +|--|--| +| *RSSI_threshold_high* | -10dB | +| *RSSI_threshold_low* | -80dB | | *RSSI_threshold_low_time_interval* | 3 seconds | -| *RSSI_sampling_period* | 2 seconds | +| *RSSI_sampling_period* | 2 seconds | -![Advertisement monitoring graph](images/HCI_Example_Advertisement_Monitoring.png) +:::image type="content" source="images/HCI_Example_Advertisement_Monitoring.png" alt-text="Advertisement monitoring graph"::: The advertisement RSSI is greater than *RSSI_threshold_high* at time 3. The periodic timer for sampling starts at time 3. Every 2 seconds, the periodic timer expires and the average RSSI value of the received advertisement is propagated to the stack. @@ -882,20 +1007,60 @@ When the periodic timer expires at time 13, the average of the advertisement RSS When *RSSI_threshold_low_time_interval* expires at instant 15, an advertisement is propagated to the host with RSSI of -85dB. No further advertisements are sent to the host in this example. +### Example: Monitoring BAP Announcements from a device + +While bonded with a CAP Acceptor, but not connected, a Host could monitor BAP Announcements from that device. + +| Parameter | Value | +|--|--| +| Subcommand_opcode_v2 | 0x0F | +| RSSI_threshold_high | -127 | +| RSSI_threshold_low | -127 | +| RSSI_threshold_low_time_interval | 0x05 | +| RSSI_sampling_period | 0x00 | +| Monitor_options | Bit 0 set; Bit 1 set if the device distributed an IRK | +| Advertisement_report_filtering_options | Bit 0, 1, and 2 set | +| Peer_device_address | \ | +| Peer_device_address_type | \
| +| Peer_device_IRK | \ | +| Condition_type | 0x01 | +| Number_of_patterns | 0x01 | +| Pattern_data | 0x04 (length)
0x16 (Service Data – 16 bit UUID)
0x00 (Start byte)
0x4E (low byte of ASCS UUID)
0x18 (high byte of ASCS UUID) | + +### Example: Monitoring CAP Announcements from a device + +While bonded with a CAP Commander, but not connected, a Host could monitor CAP Announcements from that device. + +| Parameter | Value | +|--|--| +| Subcommand_opcode_v2 | 0x0F | +| RSSI_threshold_high | -127 | +| RSSI_threshold_low | -127 | +| RSSI_threshold_low_time_interval | 0x05 | +| RSSI_sampling_period | 0x00 | +| Monitor_options | Bit 0 set; Bit 1 set if the device distributed an IRK | +| Advertisement_report_filtering_options | Bit 0, 1, and 2 set | +| Peer_device_address | \ | +| Peer_device_address_type | \
| +| Peer_device_IRK | \ | +| Condition_type | 0x01 | +| Number_of_patterns | 0x01 | +| Pattern_data | 0x04 (length)
0x16 (Service Data – 16 bit UUID)
0x00 (Start byte)
0x53 (low byte of CAS UUID)
0x18 (high byte of CAS UUID) | + ### Flowchart: Advertisement and filter accept list filtering This flowchart provides an example controller implementation of advertisement filtering and filter accept list filtering when an advertisement is received. A controller can implement this logic differently, as long as the host is notified of the advertisement or [HCI_VS_MSFT_LE_Monitor_Device_Event][ref_HCI_VS_MSFT_LE_Monitor_Device_Event] as specified by the flowchart. -![Microsoft HCI extension filtering flowchart](images/HCI_Filtering_Flowchart.png) +:::image type="content" source="images/HCI_Filtering_Flowchart.png" alt-text="Microsoft HCI extension filtering flowchart"::: ### Sequence diagram: Propagate scan response associated with advertisement Sequence diagram: Propagate scan response associated with advertisement This sequence diagram shows a propagate scan response that is associated with an advertisement that satisfies an advertisement filter when active scanning is enabled. -This diagram only shows the expected sequence of events between controller and host, and does not show events between the controller and a particular device. -Assume that there is an advertisement *A* that satisfies an advertisement filter, and an advertisement *B* that does not satisfy the advertisement filter. +This diagram only shows the expected sequence of events between controller and host, and doesn't show events between the controller and a particular device. +Assume that there's an advertisement *A* that satisfies an advertisement filter, and an advertisement *B* that doesn't satisfy the advertisement filter. -![HCI propagate scan sequence diagram](images/HCI_Propagate_Scan_Sequence.png) +:::image type="content" source="images/HCI_Propagate_Scan_Sequence.png" alt-text="HCI propagate scan sequence diagram"::: diff --git a/windows-driver-docs-pr/bluetooth/proximity-profile-implementation-details.md b/windows-driver-docs-pr/bluetooth/proximity-profile-implementation-details.md index 9e60dca6db..ce67aadd85 100644 --- a/windows-driver-docs-pr/bluetooth/proximity-profile-implementation-details.md +++ b/windows-driver-docs-pr/bluetooth/proximity-profile-implementation-details.md @@ -1,30 +1,23 @@ --- -title: Proximity Profile Implementation Details +title: Proximity Profile implementation details description: To achieve a power-efficient design, device implementations must observe specific requirements to ensure that they remain compatible with Windows. -ms.date: 04/20/2017 +ms.date: 10/06/2022 --- -# Proximity Profile Implementation Details - +# Proximity Profile implementation details To achieve a power-efficient design, device implementations must observe specific requirements to ensure that they remain compatible with Windows. The following subtopics examine device-side requirements to enable efficient use of power, as well as describe a technique by which the connection state can be monitored. -## Establishing a Connection - - -Windows 8.1 will automatically connect to a device when an application has a registered a handler for the GattCharacteristic.ValueChanged event. However the basic definition of the services included in the Proximity Profile does not contain any indicatable or notifiable characteristics. A device can add a service that contains an indicatable or notifiable characteristic to the services included in the Proximity Profile. This means that a proximity device must support at least one indicatable or notifiable characteristic value and an application must register at least one handler to a GattCharacteristic.ValueChanged event for the connection to be automatically established. +## Establishing a connection -## Detecting Loss of Connection +Windows automatically connects to a device when an application has a registered a handler for the GattCharacteristic.ValueChanged event. However, the basic definition of the services included in the Proximity Profile does not contain any indicative or notifiable characteristics. A device can add a service that contains an indicative or notifiable characteristic to the services included in the Proximity Profile. This means that a proximity device must support at least one indicative or notifiable characteristic value and an application must register at least one handler to a GattCharacteristic.ValueChanged event for the connection to be automatically established. +## Detecting loss of connection As mentioned in [Bluetooth Proximity Profile](bluetooth-proximity-profile.md), Windows 8.1 does not expose the RSSI value of Bluetooth connections. Consequently, apps cannot use the RSSI value to calculate the connection path loss. Instead, we recommend that a device tie its proximity to the link loss event. -## Monitoring the connection state - - -Apps can monitor the connection state of GATT devices by using a PnpObjectWatcher and monitor the PnP "Connected" property of the service Device Object. This technique is demonstrated in the [Bluetooth Generic Attribute Profile - Heart Rate Service](/samples/browse/) sample. - - +## Monitoring the connection state +Apps can monitor the connection state of GATT devices by using a PnpObjectWatcher and monitor the PnP "Connected" property of the service device object. diff --git a/windows-driver-docs-pr/bluetooth/querying-for-bluetooth-interfaces.md b/windows-driver-docs-pr/bluetooth/querying-for-bluetooth-interfaces.md index db4262e456..551b395ce8 100644 --- a/windows-driver-docs-pr/bluetooth/querying-for-bluetooth-interfaces.md +++ b/windows-driver-docs-pr/bluetooth/querying-for-bluetooth-interfaces.md @@ -1,6 +1,6 @@ --- -title: Querying for Bluetooth Interfaces -description: Querying for Bluetooth Interfaces +title: Querying for Bluetooth interfaces +description: Querying for Bluetooth interfaces keywords: - Bluetooth WDK , interface queries - querying Bluetooth interfaces @@ -8,64 +8,29 @@ keywords: ms.date: 04/20/2017 --- -# Querying for Bluetooth Interfaces - +# Querying for Bluetooth interfaces The Bluetooth driver stack exposes the following interfaces that profile drivers can use to interact with Bluetooth devices. - ---- - - - - - - - - - - - - - - - - - - - - -
InterfaceDescription

GUID_BTHDDI_SDP_NODE_INTERFACE

Profile drivers query for the GUID_BTHDDI_SDP_NODE_INTERFACE to obtain pointers to functions that allow them to create Service Discovery Protocol (SDP) records.

-

This interface corresponds to the BTHDDI_SDP_NODE_INTERFACE structure.

GUID_BTHDDI_SDP_PARSE_INTERFACE

Profile drivers query for the GUID_BTHDDI_SDP_PARSE_INTERFACE to obtain pointers to functions that allow them to parse SDP records.

-

This interface corresponds to the BTHDDI_SDP_PARSE_INTERFACE structure.

GUID_BTHDDI_PROFILE_DRIVER_INTERFACE

Profile drivers query for the BTHDDI_PROFILE_DRIVER_INTERFACE to obtain pointers to functions that allow them to create, allocate, reuse, and free BRBs.

-

This interface corresponds to the BTH_PROFILE_DRIVER_INTERFACE structure.

- - +| Interface | Description | +|--|--| +| GUID_BTHDDI_SDP_NODE_INTERFACE | Profile drivers query for the GUID_BTHDDI_SDP_NODE_INTERFACE to obtain pointers to functions that allow them to create Service Discovery Protocol (SDP) records.

This interface corresponds to the **[BTHDDI_SDP_NODE_INTERFACE](/windows-hardware/drivers/ddi/bthsdpddi/ns-bthsdpddi-_bthddi_sdp_node_interface)** structure. | +| GUID_BTHDDI_SDP_PARSE_INTERFACE | Profile drivers query for the GUID_BTHDDI_SDP_PARSE_INTERFACE to obtain pointers to functions that allow them to parse SDP records.

This interface corresponds to the **[BTHDDI_SDP_PARSE_INTERFACE](/windows-hardware/drivers/ddi/bthsdpddi/ns-bthsdpddi-_bthddi_sdp_parse_interface)** structure. | +| GUID_BTHDDI_PROFILE_DRIVER_INTERFACE | Profile drivers query for the BTHDDI_PROFILE_DRIVER_INTERFACE to obtain pointers to functions that allow them to create, allocate, reuse, and free BRBs.

This interface corresponds to the **[BTH_PROFILE_DRIVER_INTERFACE](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_bth_profile_driver_interface)** structure. | To obtain any of these interfaces, a profile driver must first build and send an [**IRP\_MN\_QUERY\_INTERFACE**](../kernel/irp-mn-query-interface.md) IRP to the Bluetooth driver stack. The following procedure is the general process to obtain one of these interfaces. -### To Query for an Interface - -1. Allocate and initialize an IRP. - -2. Allocate and initialize an instance of the interface. - -3. Specify the major and minor function codes to query for the interface. +## To query for an interface -4. Specify the interface to query for. +1. Allocate and initialize an IRP. +1. Allocate and initialize an instance of the interface. +1. Specify the major and minor function codes to query for the interface. +1. Specify the interface to query for. +1. Pass the IRP down the driver stack to be processed. -5. Pass the IRP down the driver stack to be processed. - -The following pseudocode example demonstrates how to set up an IRP\_MN\_QUERY\_INTERFACE IRP to query the Bluetooth driver stack for the GUID\_BTHDDI\_PROFILE\_DRIVER\_INTERFACE. - -**Note**  For readability, the following pseudocode example does not demonstrate error handling. - - +The following pseudocode example demonstrates how to set up an IRP\_MN\_QUERY\_INTERFACE IRP to query the Bluetooth driver stack for the GUID\_BTHDDI\_PROFILE\_DRIVER\_INTERFACE. For readability, the example does not demonstrate error handling. ```cpp #include @@ -101,4 +66,3 @@ Status = IoCallDriver( DeviceExtension->NextLowerDriver, Irp ); ``` If the IRP returns successfully, the profile driver can then access and use the function pointers that are contained in the interface. - diff --git a/windows-driver-docs-pr/bluetooth/serial-bus-driver-layer.md b/windows-driver-docs-pr/bluetooth/serial-bus-driver-layer.md index 99117fa5eb..2513a86d9b 100644 --- a/windows-driver-docs-pr/bluetooth/serial-bus-driver-layer.md +++ b/windows-driver-docs-pr/bluetooth/serial-bus-driver-layer.md @@ -1,45 +1,42 @@ --- -title: Serial Bus Driver Layer +title: Serial bus driver layer description: The serial bus driver is loaded based on a PDO created by ACPI, and can query and access the system resources, such as GPIO and I2C controllers to perform signaling control. -ms.date: 04/20/2017 +ms.date: 10/06/2022 --- -# Serial Bus Driver Layer - +# Serial bus driver layer The serial bus driver is loaded based on a PDO created by ACPI, and can query and access the system resources, such as GPIO and I2C controllers to perform signaling control. -## Sample Mechanism for Power Control - +## Sample mechanism for power control -Bluetooth over USB has a built-in mechanism for inband signaling to support sleep (i.e. USB selective suspend) and wake. However, in a SoC platform, the mechanism to support power control can be more flexible (and customizable) using various controllers. +Bluetooth over USB has a built-in mechanism for in-band signaling to support sleep (i.e. USB selective suspend) and wake. However, in a SoC platform, the mechanism to support power control can be more flexible (and customizable) using various controllers. The following is a sample implementation to walk through idle and wake signaling -- A GPIO interrupt HOST\_WAKE line - to signal by the Bluetooth controller when it needs to wake the host to service a request from a remote device (e.g. remote connection) -- A GPIO signal line BT\_ENABLE line - set by a bus driver and is asserted when the radio is active (core stack in D0) or is de-asserted when Bluetooth core stack has detected idleness (entering into D2). - -These two GPIO lines in the form of system resources will be reported to the serial bus driver during driver loading as a regular interrupt and a new GPIO signal. Its interconnection properties will be defined in the ACPI table by the system integrator and the Bluetooth chipset vendor (IHV). A serial bus driver can query and cache these dependent controller’s connection IDs in order to open and access their resources. +- A GPIO interrupt HOST\_WAKE line - to signal by the Bluetooth controller when it needs to wake the host to service a request from a remote device (e.g. remote connection) +- A GPIO signal line BT\_ENABLE line - set by a bus driver and is asserted when the radio is active (core stack in D0) or is de-asserted when Bluetooth core stack has detected idleness (entering into D2). -## Startup to Enable Idle +These two GPIO lines in the form of system resources will be reported to the serial bus driver during driver loading as a regular interrupt and a new GPIO signal. Its interconnection properties will be defined in the ACPI table by the system integrator and the Bluetooth chipset vendor (IHV). A serial bus driver can query and cache these dependent controller's connection IDs in order to open and access their resources. +## Startup to enable idle -The serial bus driver is required to perform the following tasks for supporting idle in the S0 sytem power state: +The serial bus driver is required to perform the following tasks for supporting idle in the S0 system power state: -1. Report PnP and power management capabilities; as an integrated device, its Removeable flag for the child PDO should be set to WdfFalse. -2. Report that it can support idle to its function driver (Bluetooth core driver). -3. Handle arm and disarm for wake, and wake signal. -4. Receive device power state notification and synchronize I/O completion with current device power state. +1. Report PnP and power management capabilities; as an integrated device, its Removable flag for the child PDO should be set to WdfFalse. +1. Report that it can support idle to its function driver (Bluetooth core driver). +1. Handle arm and disarm for wake, and wake signal. +1. Receive device power state notification and synchronize I/O completion with current device power state. -**Power Management Capabilities** +### Power management capabilities The child PDO created by the bus driver sets power capabilities to enable idle state support and will be managed by the Power Manager, including settings to indicate such as: -- Its capability to support D2 device state. -- Its capability to enter idle and wake from D2. -- Its mapping of system state to device states and be in sync with the Bluetooth core driver. +- Its capability to support D2 device state. +- Its capability to enter idle and wake from D2. +- Its mapping of system state to device states and be in sync with the Bluetooth core driver. -``` syntax +```cpp WDF_DEVICE_POWER_CAPABILITIES_INIT(&PowerCaps); … PowerCaps.DeviceD1 = WdfFalse; @@ -59,7 +56,7 @@ WdfDeviceSetPowerCapabilities(ChildDevice, &PowerCaps); The child PDO creates a WDF queue to receive IOCTL (I/O Control) request from the Bluetooth core driver. Such requests do come to query for the interface version and static capabilities prior to the device being started; therefore, this queue must not be power managed. -``` syntax +```cpp QueueConfig.PowerManaged = WdfFalse; QueueConfig.EvtIoDeviceControl = PdoIoQuDeviceControl; @@ -70,19 +67,19 @@ Status = WdfIoQueueCreate(ChildDevice, &Queue); ``` -**Bluetooth Transport Specific Query for Idle Capability** +### Bluetooth transport specific query for idle capability -In addition to reporting power management capabilities (as highlighted in the prior section), the child PDO also responds to the Bluetooth core driver’s query for its capabilities to enter the idle state. In order to support idle in S0, this flag is set: +In addition to reporting power management capabilities (as highlighted in the prior section), the child PDO also responds to the Bluetooth core driver's query for its capabilities to enter the idle state. In order to support idle in S0, this flag is set: -``` syntax +```cpp FdoExtension->BthXCaps.IsDeviceIdleCapable = TRUE; ``` -**Arm and Disarm for Wake** +### Arm and disarm for wake A requirement for idle support is the ability to receive a wake request from a remote Bluetooth device. The setup for such a wake request involves being armed for wake. The PDO for the Bluetooth function can register to receive callbacks to accomplish arm/disarm actions: -``` syntax +```cpp WDF_PDO_EVENT_CALLBACKS_INIT(&Callbacks); // Receive this callback to arming the device for wake @@ -96,11 +93,11 @@ WdfPdoInitSetEventCallbacks(DeviceInit, &Callbacks); With the above mechanisms supported, the Bluetooth core driver can then enable idle and wake support. -**Device Power State Notification** +### Device power state notification Child PDO registers to receive a callback to enter and exit D0 in order to be notified of the device power state transition. The current device power state is used to synchronize IO completion – i.e. normal IO completion should only be completed in D0. -``` syntax +```cpp // // Register to receive device power state change notification // @@ -114,15 +111,13 @@ Child PDO registers to receive a callback to enter and exit D0 in order to be no &PnpPowerCallbacks); ``` -## Arm for Wake - +## Arm for wake Prior to entering idle, the serial bus driver will receive the callback [**EvtDeviceEnableWakeAtBus**](/windows-hardware/drivers/ddi/wdfpdo/nc-wdfpdo-evt_wdf_device_enable_wake_at_bus) to arm for wake. The mechanism to arm for wake is vendor specific for SoC platforms and is thus outside the scope of this section. However, Windows expects that the bus driver will be prepared to receive a wake signal, and there will be a callback function (e.g. ISR) to process such a signal. -## Enter Idle - +## Enter idle The Bluetooth core driver enables a time-based idle detection mechanism. Upon satisfying idle requirements, the core driver starts to initiate the stack to enter the idle state. It invokes [**PoRequestPowerIrp**](/windows-hardware/drivers/ddi/wdm/nf-wdm-porequestpowerirp) to set the power to go into D2 along with a completion function. After the bus driver has completed the IRP, this completion function is invoked. It is at this time, the transition to D2 gets completed. @@ -130,17 +125,16 @@ While transitioning into idle state, the Bluetooth core driver will cancel all p In addition to idle timeout, the Bluetooth core driver takes into consideration many different situations before entering into the idle state, such as: -- Wait for the completion of an HCI Command that it has just issued. Note: the Bluetooth core driver will not enter idle until its completion. -- All connected devices are in sniff mode. +- Wait for the completion of an HCI Command that it has just issued. Note: the Bluetooth core driver will not enter idle until its completion. +- All connected devices are in sniff mode. In this idle state, the multifunction controller has the option to throttle down its power by the Bluetooth function, but it must continue to supply power to maintain its volatile settings and configuration. It can then rely on its wake mechanism to wake the stack back to active (D0) state after which I/O communication can resume. -## Wake from Sleep - +## Wake from sleep While the Bluetooth function has been paired with one or more devices and is in the sleep state, its radio is periodically scanning for requests from its paired devices. When a paired device initiates a request and gets received by the Bluetooth radio, the process to resume to active state begins. Once the device stack has resumed to active (D0), the drivers can begin servicing this remote request. -This remote request is processed by the wake-signal processing function in the bus driver as discussed in the last section. This wake-signal processing function should ensure that the PDO’s device state is indeed in D2 state and then invoke [**WdfDeviceIndicateWakeStatus**](/windows-hardware/drivers/ddi/wdfdevice/nf-wdfdevice-wdfdeviceindicatewakestatus) (PDO, success status) to notify KMDF to complete the W/W (Wait Wake) IRP. It is at this time when the completion function of this W/W IRP can be invoked and get processed by its initiator - the Bluetooth core driver and the power policy owner. +This remote request is processed by the wake-signal processing function in the bus driver as discussed in the last section. This wake-signal processing function should ensure that the PDO's device state is indeed in D2 state and then invoke [**WdfDeviceIndicateWakeStatus**](/windows-hardware/drivers/ddi/wdfdevice/nf-wdfdevice-wdfdeviceindicatewakestatus) (PDO, success status) to notify KMDF to complete the W/W (Wait Wake) IRP. It is at this time when the completion function of this W/W IRP can be invoked and get processed by its initiator - the Bluetooth core driver and the power policy owner. The completion of the W/W IRP triggers the Bluetooth core driver to initiate a transition to D0. It requests a [**PoRequestPowerIrp**](/windows-hardware/drivers/ddi/wdm/nf-wdm-porequestpowerirp) with a completion function to set the device power state to D0. @@ -150,25 +144,20 @@ After Bluetooth driver stack resumes to D0, the serial bus driver can then compl Some events need to be synchronized in the serial bus driver, such as: -- While entering D2, there should already be a pending W/W Irp. This is when arming for wake to receive the wake signal should take place instead of when receiving a W/W Irp. The wake signal is only actionable while in D2 state. -- If data is arriving (to form a packet) while entering D2 and there is no pending read request in the queue, the bus driver can cache the incoming data and enter D2. It can then complete the W/W Irp (with success) to wake the system back to D0 to re-pend and complete the read request. -- Bthport cancels all pending read requests and waits for their completion before entering D2. At the same time, the serial bus driver may have received a complete HCI packet and has de-queued a read request to return this HCI packet. The serial bus driver should complete this request, and will then be initiated to enter D2. +- While entering D2, there should already be a pending W/W Irp. This is when arming for wake to receive the wake signal should take place instead of when receiving a W/W Irp. The wake signal is only actionable while in D2 state. +- If data is arriving (to form a packet) while entering D2 and there is no pending read request in the queue, the bus driver can cache the incoming data and enter D2. It can then complete the W/W Irp (with success) to wake the system back to D0 to re-pend and complete the read request. +- Bthport cancels all pending read requests and waits for their completion before entering D2. At the same time, the serial bus driver may have received a complete HCI packet and has de-queued a read request to return this HCI packet. The serial bus driver should complete this request, and will then be initiated to enter D2. An action initiated by a Bluetooth application on the host side can also wake the stack from idle. In this case, only the device power state transition is required, and this action is initiated by the Bluetooth core driver. In order to reduce power up time, the callback functions (e.g. the EnterD0 and wake) in the serial bus driver should not be marked pageable. -## A flowchart to express the idle/wake, arm/disarm, and device power state transitions - +## A flowchart to express the idle/wake, arm/disarm, and device power state transitions The following is a simplified flowchart to illustrate a typical sequence and logic for idle and wake support. This logic spans many drivers and threads, and there are exceptions as well as corner cases that are not expressed (e.g. an application on the host side can also wake the stack from idle state). -![bluetooth device power state transitions flowchart.](images/bthdevicepwrstatetransitionsflowchart.png) - -## Bus Driver’s own Power Management - - -The serial bus driver is a function driver (FD) and the power policy owner (PPO) of its layer. Thus, it needs to handle its own power management. After all of its children have entered lower device power states, it can then enter into a lower power state itself. When it’s ready to enter this lower power state, it can cancel any pending I/O requests to the UART controller driver – this will allow the UART driver to also enter a lower power state. However, the UART driver should persist and restore its device settings (including the baud rate) when its power state is later resumed to active. +:::image type="content" source="images/bthdevicepwrstatetransitionsflowchart.png" alt-text="Flowchart showing Bluetooth device power state transitions."::: - +## Bus driver's own power management +The serial bus driver is a function driver (FD) and the power policy owner (PPO) of its layer. Thus, it needs to handle its own power management. After all of its children have entered lower device power states, it can then enter into a lower power state itself. When it's ready to enter this lower power state, it can cancel any pending I/O requests to the UART controller driver – this will allow the UART driver to also enter a lower power state. However, the UART driver should persist and restore its device settings (including the baud rate) when its power state is later resumed to active. diff --git a/windows-driver-docs-pr/bluetooth/supporting-bluetooth-event-notifications.md b/windows-driver-docs-pr/bluetooth/supporting-bluetooth-event-notifications.md index 4e7195f83e..d9a551dfaa 100644 --- a/windows-driver-docs-pr/bluetooth/supporting-bluetooth-event-notifications.md +++ b/windows-driver-docs-pr/bluetooth/supporting-bluetooth-event-notifications.md @@ -1,136 +1,79 @@ --- -title: Supporting Bluetooth Event Notifications -description: Supporting Bluetooth Event Notifications +title: Supporting Bluetooth event notifications +description: Supporting Bluetooth event notifications keywords: - Bluetooth WDK , event notifications - event notifications WDK Bluetooth - notifications WDK Bluetooth - profile drivers WDK Bluetooth -ms.date: 04/20/2017 +ms.date: 10/06/2022 --- -# Supporting Bluetooth Event Notifications - +# Supporting Bluetooth event notifications When a profile driver opens a connection to a remote device, it should register itself to be notified when the connection is closed, or when any other changes to the connection occur. Additionally, when a profile driver registers itself to accept incoming connections, it must be able to be notified when a remote device attempts to connect to it. -Profile drivers that use Synchronous Connection-Oriented (SCO) connection implement and register a [*SCO Callback Function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnsco_indication_callback). A client profile driver registers the appropriate callback function when it requests a connection to a remote device. +Profile drivers that use Synchronous Connection-Oriented (SCO) connection implement and register a [*SCO callback function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnsco_indication_callback). A client profile driver registers the appropriate callback function when it requests a connection to a remote device. -When a SCO profile driver issues a **BRB\_SCO\_OPEN\_CHANNEL** BRB, it specifies a pointer to its [*SCO Callback Function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnsco_indication_callback) in the **Callback** member of the BRB's corresponding [**\_BRB\_SCO\_OPEN\_CHANNEL**](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_brb_sco_open_channel) structure. If the remote device accepts the SCO connection request, the Bluetooth driver stack can then send notifications to the profile driver through the callback function when a change occurs to the SCO connection . +When a SCO profile driver issues a **BRB_SCO_OPEN_CHANNEL** BRB, it specifies a pointer to its [*SCO callback function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnsco_indication_callback) in the **Callback** member of the BRB's corresponding [**_BRB_SCO_OPEN_CHANNEL**](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_brb_sco_open_channel) structure. If the remote device accepts the SCO connection request, the Bluetooth driver stack can then send notifications to the profile driver through the callback function when a change occurs to the SCO connection . For more information about creating SCO connections, see [Creating a SCO Client Connection to a Remote Device](creating-a-sco-client-connection-to-a-remote-device.md). -Profile drivers that use Logical Link Controller and Adaptation Protocol (L2CAP) connections implement and register an [*L2CAP Callback Function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnbthport_indication_callback). +Profile drivers that use Logical Link Controller and Adaptation Protocol (L2CAP) connections implement and register an [*L2CAP callback function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnbthport_indication_callback). -When a L2CAP profile driver issues a **BRB\_L2CA\_OPEN\_CHANNEL** BRB, it specifies a pointer to its [*L2CAP Callback Function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnbthport_indication_callback) in the **Callback** member of the BRB's corresponding [**\_BRB\_L2CA\_OPEN\_CHANNEL**](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_brb_l2ca_open_channel) structure. If the remote device accepts the L2CAP connection request, the Bluetooth driver stack can then send notifications to the profile driver through the callback function when a change occurs to the L2CAP connection. +When a L2CAP profile driver issues a **BRB_L2CA_OPEN_CHANNEL** BRB, it specifies a pointer to its [*L2CAP callback function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnbthport_indication_callback) in the **Callback** member of the BRB's corresponding [**_BRB_L2CA_OPEN_CHANNEL**](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_brb_l2ca_open_channel) structure. If the remote device accepts the L2CAP connection request, the Bluetooth driver stack can then send notifications to the profile driver through the callback function when a change occurs to the L2CAP connection. For more information about creating L2CAP connections, see [Creating a L2CAP Client Connection to a Remote Device](creating-a-l2cap-client-connection-to-a-remote-device.md). Similarly, when a profile driver registers itself to accept incoming (L2CAP, SCO) connection requests, it must register a callback function to be notified when a remote device attempts to connect to it. -Profile drivers that use L2CAP specify their [*L2CAP Callback Function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnbthport_indication_callback) in the **IndicationCallback** member of the [**\_BRB\_L2CA\_REGISTER\_SERVER**](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_brb_l2ca_register_server) structure. The Bluetooth driver stack can then call the callback function to notify the profile driver when a remote device attempts to initiate a L2CAP connection to the profile driver. +Profile drivers that use L2CAP specify their [*L2CAP callback function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnbthport_indication_callback) in the **IndicationCallback** member of the [**_BRB_L2CA_REGISTER_SERVER**](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_brb_l2ca_register_server) structure. The Bluetooth driver stack can then call the callback function to notify the profile driver when a remote device attempts to initiate a L2CAP connection to the profile driver. -Profile drivers that use SCO specify their [*SCO Callback Function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnsco_indication_callback) in the **IndicationCallback** member of the [**\_BRB\_SCO\_REGISTER\_SERVER**](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_brb_sco_register_server) structure. The Bluetooth driver stack can then call the callback function to notify the profile driver when a remote device attempts to initiate a SCO connection to the profile driver. +Profile drivers that use SCO specify their [*SCO callback function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnsco_indication_callback) in the **IndicationCallback** member of the [**_BRB_SCO_REGISTER_SERVER**](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_brb_sco_register_server) structure. The Bluetooth driver stack can then call the callback function to notify the profile driver when a remote device attempts to initiate a SCO connection to the profile driver. After the profile driver registers the appropriate callback function, the Bluetooth driver stack can also notify the profile driver if and when an event occurs across the open connection. -**Note**  A profile driver can register the same callback function to send it change notifications about an open channel and about remote devices attempting to connect to it. - - +> [!NOTE] +> A profile driver can register the same callback function to send it change notifications about an open channel and about remote devices attempting to connect to it. For L2CAP connections, the [*L2CAP callback function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnbthport_indication_callback) accepts three parameters: -- The context that is defined for the L2CAP connection. In the case of BRB\_L2CA\_REGISTER\_SERVER requests, this context is the value passed in the **IndicationCallbackContext** member of the \_BRB\_L2CA\_REGISTER\_SERVER structure passed with the request. In the case of **BRB\_L2CA\_OPEN\_CHANNEL** or **BRB\_L2CA\_OPEN\_CHANNEL\_RESPONSE** requests, this context is the value passed in the **CallbackContext** member of the \_BRB\_L2CA\_OPEN\_CHANNEL structure passed with the request. - -- A value from the [**INDICATION\_CODE**](/windows-hardware/drivers/ddi/bthddi/ne-bthddi-_indication_code) enumeration that indicates the type of the notification event of the incoming L2CAP connection or bonding state change. - -- A pointer to an [**INDICATION\_PARAMETERS**](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_indication_parameters) structure that contains the parameters associated with the notification event. - -The value passed in the [*L2CAP callback function's*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnbthport_indication_callback)*Indication* parameter specifies which union member in the **Parameters** union of the *Parameters* parameter that the profile driver should use. - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
If the value of the Indication parameter equals......use the following union member of the Parameters parameter

IndicationRemoteConnect

Connect

IndicationRemoteConfigRequest

ConfigRequest

IndicationRemoteConfigResponse

ConfigResponse

IndicationFreeExtraOptions

FreeExtraOptions

IndicationRemoteDisconnect

Disconnect

IndicationRecvPacket

RecvPacket

- - +- The context that is defined for the L2CAP connection. In the case of BRB_L2CA_REGISTER_SERVER requests, this context is the value passed in the **IndicationCallbackContext** member of the \_BRB_L2CA_REGISTER_SERVER structure passed with the request. In the case of **BRB_L2CA_OPEN_CHANNEL** or **BRB_L2CA_OPEN_CHANNEL_RESPONSE** requests, this context is the value passed in the **CallbackContext** member of the _BRB_L2CA_OPEN_CHANNEL structure passed with the request. -For SCO connections, the [*SCO callback function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnsco_indication_callback) accepts three arguments: +- A value from the [**INDICATION_CODE**](/windows-hardware/drivers/ddi/bthddi/ne-bthddi-_indication_code) enumeration that indicates the type of the notification event of the incoming L2CAP connection or bonding state change. -- The context that is defined for the SCO connection. In the case of **BRB\_SCO\_REGISTER\_SERVER** requests, this context is the value passed in the **IndicationCallbackContext** member of the \_BRB\_SCO\_REGISTER\_SERVER structure passed with the request. In the case of **BRB\_SCO\_OPEN\_CHANNEL** or **BRB\_SCO\_OPEN\_CHANNEL\_RESPONSE** requests, this context is the value passed in the **CallbackContext** member of the \_BRB\_SCO\_OPEN\_CHANNEL structure passed with the request. +- A pointer to an [**INDICATION_PARAMETERS**](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_indication_parameters) structure that contains the parameters associated with the notification event. -- A value from the [**SCO\_INDICATION\_CODE**](/windows-hardware/drivers/ddi/bthddi/ne-bthddi-_sco_indication_code) enumeration that indicates the type of the notification of the incoming SCO connection or bonding state change. +The value passed in the [*L2CAP callback function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnbthport_indication_callback)'s *Indication* parameter specifies which union member in the **Parameters** union of the *Parameters* parameter that the profile driver should use. -- A pointer to a [**SCO\_INDICATION\_PARAMETERS**](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_sco_indication_parameters) structure that contains the parameters associated with the notification event. +| If the value of the *Indication* parameter equals... | ...use the following union member of the *Parameters* parameter | +|--|--| +| IndicationRemoteConnect | *Connect* | +| IndicationRemoteConfigRequest | *ConfigRequest* | +| IndicationRemoteConfigResponse | *ConfigResponse* | +| IndicationFreeExtraOptions | *FreeExtraOptions* | +| IndicationRemoteDisconnect | *Disconnect* | +| IndicationRecvPacket | *RecvPacket* | + +For SCO connections, the [*SCO callback function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnsco_indication_callback) accepts three arguments: -The value passed in the [*SCO callback function's*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnsco_indication_callback)*Indication* parameter specifies which union member in the **Parameters** union of the *Parameters* parameter that the profile driver should use. +- The context that is defined for the SCO connection. In the case of **BRB_SCO_REGISTER_SERVER** requests, this context is the value passed in the **IndicationCallbackContext** member of the \_BRB_SCO_REGISTER_SERVER structure passed with the request. In the case of **BRB_SCO_OPEN_CHANNEL** or **BRB_SCO_OPEN_CHANNEL_RESPONSE** requests, this context is the value passed in the **CallbackContext** member of the _BRB_SCO_OPEN_CHANNEL structure passed with the request. - ---- - - - - - - - - - - - - - - - - -
If the value of the Indication parameter equals......use the following union member of the Parameters parameter

ScoIndicationRemoteConnect

Connect

ScoIndicationRemoteDisconnect

Disconnect

+- A value from the [**SCO_INDICATION_CODE**](/windows-hardware/drivers/ddi/bthddi/ne-bthddi-_sco_indication_code) enumeration that indicates the type of the notification of the incoming SCO connection or bonding state change. - +- A pointer to a [**SCO_INDICATION_PARAMETERS**](/windows-hardware/drivers/ddi/bthddi/ns-bthddi-_sco_indication_parameters) structure that contains the parameters associated with the notification event. -### Handling Plug and Play Removal IRPs +The value passed in the [*SCO callback function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnsco_indication_callback)'s *Indication* parameter specifies which union member in the **Parameters** union of the *Parameters* parameter that the profile driver should use. -Profile drivers should pass all [**IRP\_MN\_SURPRISE\_REMOVAL**](../kernel/irp-mn-surprise-removal.md) IRPs down the stack immediately to be processed by the Bluetooth driver stack. Do not attempt to close any open channels as part of processing a surprise removal IRP. Do not build and send any further BRBs that send data to the underlying radio after receiving a surprise removal IRP. However, profile drivers can perform other cleanup while processing a surprise removal IRP. +| If the value of the *Indication* parameter equals... | ...use the following union member of the *Parameters* parameter | +|--|--| +| ScoIndicationRemoteConnect | *Connect* | +| ScoIndicationRemoteDisconnect | *Disconnect* | -After the Bluetooth driver stack receives the surprise removal IRP, it will pass *ScoIndicationRemoteDisconnect* to the [*SCO Callback Function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnsco_indication_callback) that was specified by the profile driver when the profile driver built and sent a [**BRB\_SCO\_OPEN\_CHANNEL**](/previous-versions/ff536626(v=vs.85)) or [**BRB\_SCO\_OPEN\_CHANNEL\_RESPONSE**](/previous-versions/ff536627(v=vs.85)) request, to close any SCO channels that are currently open. Likewise, the Bluetooth driver stack will pass *IndicationRemoteDisconnect* to the [*L2CAP Callback Function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnbthport_indication_callback) that was specified by the profile driver when the profile driver built and sent a [**BRB\_L2CA\_OPEN\_CHANNEL**](/previous-versions/ff536615(v=vs.85)) or [**BRB\_L2CA\_OPEN\_CHANNEL\_RESPONSE**](/previous-versions/ff536616(v=vs.85)) request, to close any L2CAP channels that are currently open. +## Handling Plug and Play removal IRPs -Profile drivers should unregister all servers when processing [**IRP\_MN\_REMOVE\_DEVICE**](../kernel/irp-mn-remove-device.md) IRPs. To unregister a SCO server, a profile driver should [build and send](building-and-sending-a-brb.md) a [**BRB\_SCO\_UNREGISTER\_SERVER**](/previous-versions/ff536630(v=vs.85)) request. To unregister an L2CAP server, a profile driver should build and send a [**BRB\_L2CA\_UNREGISTER\_SERVER**](/previous-versions/ff536619(v=vs.85)) request. +Profile drivers should pass all [**IRP_MN_SURPRISE_REMOVAL**](../kernel/irp-mn-surprise-removal.md) IRPs down the stack immediately to be processed by the Bluetooth driver stack. Do not attempt to close any open channels as part of processing a surprise removal IRP. Do not build and send any further BRBs that send data to the underlying radio after receiving a surprise removal IRP. However, profile drivers can perform other cleanup while processing a surprise removal IRP. - +After the Bluetooth driver stack receives the surprise removal IRP, it will pass *ScoIndicationRemoteDisconnect* to the [*SCO callback function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnsco_indication_callback) that was specified by the profile driver when the profile driver built and sent a [**BRB_SCO_OPEN_CHANNEL**](/previous-versions/ff536626(v=vs.85)) or [**BRB_SCO_OPEN_CHANNEL_RESPONSE**](/previous-versions/ff536627(v=vs.85)) request, to close any SCO channels that are currently open. Likewise, the Bluetooth driver stack will pass *IndicationRemoteDisconnect* to the [*L2CAP callback function*](/windows-hardware/drivers/ddi/bthddi/nc-bthddi-pfnbthport_indication_callback) that was specified by the profile driver when the profile driver built and sent a [**BRB_L2CA_OPEN_CHANNEL**](/previous-versions/ff536615(v=vs.85)) or [**BRB_L2CA_OPEN_CHANNEL_RESPONSE**](/previous-versions/ff536616(v=vs.85)) request, to close any L2CAP channels that are currently open. +Profile drivers should unregister all servers when processing [**IRP_MN_REMOVE_DEVICE**](../kernel/irp-mn-remove-device.md) IRPs. To unregister a SCO server, a profile driver should [build and send](building-and-sending-a-brb.md) a [**BRB_SCO_UNREGISTER_SERVER**](/previous-versions/ff536630(v=vs.85)) request. To unregister an L2CAP server, a profile driver should build and send a [**BRB_L2CA_UNREGISTER_SERVER**](/previous-versions/ff536619(v=vs.85)) request. diff --git a/windows-driver-docs-pr/bluetooth/testing-BTP-hw-bm64.md b/windows-driver-docs-pr/bluetooth/testing-BTP-hw-bm64.md index 0ff833cece..9836750346 100644 --- a/windows-driver-docs-pr/bluetooth/testing-BTP-hw-bm64.md +++ b/windows-driver-docs-pr/bluetooth/testing-BTP-hw-bm64.md @@ -1,13 +1,11 @@ --- title: Microsoft Bluetooth Test Platform - BM-64-EVB board description: Bluetooth Test Platform (BTP) supported hardware (BM64). -ms.date: 06/09/2021 +ms.date: 04/11/2023 --- # BM-64-EVB board -## Overview - The BM64 is a dual-mode Bluetooth v5.0 radio designed for use in headsets, speakers, or multi-speaker peripherals. More information can be found via the BM64 page from [**Microchip Technology Incorporated**](https://www.microchip.com/wwwproducts/en/BM64). The BM-64-EVB allows the BM64 to be utilized as a stand-alone device, allowing for connection to a test machine without the need for a Traduci. More information can be found via the BM-64-EVB page from [**Microchip**](https://www.microchip.com/DevelopmentTools/ProductDetails/PartNO/BM-64-EVB-C2). | Device Name | Parameter | Usage Example | @@ -67,51 +65,51 @@ Some configuration notes before starting: ## Flashing Firmware for the BM64 -This section will explain how to upload new firmware for the BM64. The `isupdate.exe` tool (found at `DSPK v2.x.y Package\Tools\FlashUpdate Tool`) will be used to upload new hex files to the BM64. +This section explains how to upload new firmware for the BM64. The `isupdate.exe` tool (found at `DSPK v2.x.y Package\Tools\FlashUpdate Tool`) is used to upload new hex files to the BM64. 1. Set SW9 position 1 and 2 to both ON and ensure JP33 is removed. 1. Plug the Micro-B USB cable into P3 (labeled *UART* on the EVB). 1. Start the `isupdate.exe` tool and select the COM port associated with the BM-64-EVB (use `Device Manager` and look for *Ports (COM & LPT)*). -1. The settings should be a *baud rate* set to *115200*, *image num* set to *16*, *memory* set to *flash*, *subtype* set to *Serial Flash*. After being set, click *Connect*. - - If the connection is correct, then *Device* on the right should be populated with information and *Port connect -> COM#* should be in the bottom pane. It should look like the image below (with corresponding COM ports). - - The given *baud rate* only applies to the default device for this example. If EEPROM changes have occured to modify the baud rate of the BM64, use that new value instead. +1. The settings should be a *baud rate* set to *115200*, *image num* set to *16*, *memory* set to *flash*, *subtype* set to *Serial Flash*. After being set, select *Connect*. + - If the connection is correct, then *Device* should be populated with information and *Port connect -> COM#* should be in the bottom pane. It should look like the following image (with corresponding COM ports). + - The given *baud rate* only applies to the default device for this example. If EEPROM changes have occurred to modify the baud rate of the BM64, use that new value instead. :::image type="content" source="images/btp-bm64-isupdate.png" alt-text="Photo of the isUpdate tool after connection."::: -1. Click *Browse* and navigate to the BM64 hex files in the DSPK (found at `DSPK v2.x.y Package\Software\Firmware Image\BM64 Firmware`). Highlight all 16 files (`BT5506_SHS_FLASH.H00` through `BT5506_SHS_FLASH.H15`) simultaneously and click *Open*. -1. Click *Update* to update the BM64's firmware. The bottom pane will show progress as the update occurs. **DO NOT INTERRUPT THIS PROCESS AT THE RISK OF CORRUPTING THE DEVICE.** -1. *End of Write Memory* will appear in the bottom pane once the update process is completed. Afterwards, click *Disconnect*. Wait until *port disconnect* message in the bottom pane appears. +1. Select *Browse* and navigate to the BM64 hex files in the DSPK (found at `DSPK v2.x.y Package\Software\Firmware Image\BM64 Firmware`). Highlight all 16 files (`BT5506_SHS_FLASH.H00` through `BT5506_SHS_FLASH.H15`) simultaneously and select *Open*. +1. Select *Update* to update the BM64's firmware. The bottom pane shows progress as the update occurs. **DO NOT INTERRUPT THIS PROCESS AT THE RISK OF CORRUPTING THE DEVICE.** +1. *End of Write Memory* appears in the bottom pane once the update process is completed. Afterwards, select *Disconnect*. Wait until *port disconnect* message in the bottom pane appears. 1. Remove the Micro-B USB cable, **set SW9 position 1 and 2 to both OFF**, and then plug the Micro-B USB back into P3. ## Updating EEPROM for the BM64 -This section will explain how to upload new EEPROM parameters for the BM64. The EEPROM update process involves using the `UITool_IS206x_012_DualModeSPK_v2.x.y.exe` +This section explains how to upload new EEPROM parameters for the BM64. The EEPROM update process involves using the `UITool_IS206x_012_DualModeSPK_v2.x.y.exe` tool (found at `DSPK v2.x.y Package\Tools\UI Tool`) to make a user interface files to set parameters such as baud rate or enabling UART. It then involves using the `DSPTool_IS206X_012_DUALMODESPK2.1_E1.0_V13.exe` tool (found at `DSPK v2.x.y Package\Tools\DSP Tool`) to make a DSP file for setting speaker and input filtering configurations. After a UI and DSP file are generated, the process utilizes the `MPET.exe` tool (found at `DSPK v2.x.y Package\Tools\MP_V2.x.y`) to combine for the full EEPROM *.ipf* file. Using -the generated *.ipf* tool, the actual upload of the EEPROM to the BM64 will occur with the `EEPROM_Tool.exe` tool (found at `DSPK v2.x.y Package\Tools\EEPROM_Tool`). +the generated *.ipf* tool, the actual upload of the EEPROM to the BM64 occurs with the `EEPROM_Tool.exe` tool (found at `DSPK v2.x.y Package\Tools\EEPROM_Tool`). Follow the [**guide**](http://ww1.microchip.com/downloads/en/DeviceDoc/50002514B.pdf) provided by Microchip for updating the BM64 EEPROM, -specifically sections 3.4 - "CONFIGURING BM64 MODULE" and 3.5 - "UPDATING EEPROM PARAMETERS". Below are some important modifications to the guide: +specifically sections 3.4 - "CONFIGURING BM64 MODULE" and 3.5 - "UPDATING EEPROM PARAMETERS". Here are some important modifications to the guide: - Section 3.4.1 - "UI Tool Configuration" Modifications: - 3.4.1.3: Load the *UITool_IS206x_012_DualModeSPK_v2.x.y_BM64_EVB.txt* UI parameters starting text file. - 3.4.1.4: Select "BM64CLS2" for the *IC Package* if using a BM-64-EVB-C2 and "BM64CLS1" if using a BM-64-EVB-C1 board. - - 3.4.1.6: Changing the *Name Fragment* is optional and will not impact use (if changed, make sure the name is more than 0 and less than 32 ASCII characters). - - 3.4.1.12: Do not overwrite an existing table in case of wanting to use the default table if there is a critical error with the board. + - 3.4.1.6: Changing the *Name Fragment* is optional and doesn't affect use (if changed, make sure the name is more than 0 and less than 32 ASCII characters). + - 3.4.1.12: Don't overwrite an existing table when wanting to use the default table if there's a critical error with the board. - Section 3.4.2 - "DSP Tool Configuration" Modifications: - 3.4.2.1: Select "IS206X_012_DUALMODESPK2.1_E1.0" (or similar) for the *IC Version*. - Section 3.4.3 - "MPET Tool Configuration" Modifications: - 3.4.3.3: Select "IS206X_012_DUALMODESPK2.1_E1.0.4.1_1214.bin" (or similar) for the default *.bin* file. - 3.4.3.5: Add and merge the files created in Section 3.4.1 and Section 3.4.2 of the guide. - - 3.4.3.8: The popup may not occur depending on the version of DPSK being used, which will not impact performance. + - 3.4.3.8: The popup may not occur depending on the version of DPSK being used, which doesn't affect performance. - Section 3.5 - "UPDATING EEPROM PARAMETERS" Modifications: - - 3.5.1: Unplug the USB, if not alread, before starting. - - 3.5.5: Use the *.ipf* generated from Section 3.4.3. Additionally, a pop up may occur warning of the size of file of the *.ipf*. Click *OK* (this happens with default tables as well). + - 3.5.1: Unplug the USB, if not already, before starting. + - 3.5.5: Use the *.ipf* generated from Section 3.4.3. Additionally, a pop up may occur warning of the size of file of the *.ipf*. Select *OK* (this warning happens with default tables as well). - 3.5.6: **DO NOT INTERRUPT THIS PROCESS AT THE RISK OF CORRUPTING THE DEVICE**. -## Verifying Installation with SPKCommand +## Verifying installation with SPKCommand -After firmware and EEPROM updates occur, the UART messaging capabilies of the BM-64-EVB necessary for communicating with BTP can be verified using the SPKCommand tool included in the DSPK. +After firmware and EEPROM updates occur, the UART messaging capabilities of the BM-64-EVB necessary for communicating with BTP can be verified using the SPKCommand tool included in the DSPK. 1. Set SW9 position 1 and 2 to both OFF and ensure JP33 jumper is removed. 1. Plug the Micro-B USB cable into P3 (labeled *UART* on the EVB). @@ -120,26 +118,26 @@ After firmware and EEPROM updates occur, the UART messaging capabilies of the BM - Set the *Port* to the COM port associated with the BM-64-EVB. - Set the *Baudrate* to *19200* per the EEPROM updates. -1. Click on the *Open* button. Messages may appear in the bottom log to the right. -1. Click on the *Information* tab and click on the *Update* button. +1. Select on the *Open* button. Messages may appear in the bottom log to the right. +1. Select on the *Information* tab and select on the *Update* button. - - If UART messages are being communicated correctly, the information such as the *Local Device Name* and *Bluetooth Address* will be populated on the left and the logs on the right will show both *Event:* and *Command:* messages followed by hex codes representing the UART message contents. - - If no BM64 information is populated and only *Command:* messages are seen in the logs, try closing and reopening the connection. If the expected behavior still does not occur, refer to the [Further Help](testing-BTP-hw-bm64.md#further-help) section below. + - If UART messages are being communicated correctly, the information such as the *Local Device Name* and *Bluetooth Address* is populated, and the logs show both *Event:* and *Command:* messages followed by hex codes representing the UART message contents. + - If no BM64 information is populated and only *Command:* messages are seen in the logs, try closing and reopening the connection. If the expected behavior still doesn't occur, refer to the [Further Help](testing-BTP-hw-bm64.md#further-help) section. :::image type="content" source="images/btp-bm64-spkcommand.png" alt-text="Photo of the SPKCommand after the correct messages are sent."::: ## Using the BM-64-EVB -After new firmware and EEPROM is installed, make sure JP33 jumper is removed and SW9 positions 1 and 2 are both OFF. Additionally, set all positions of SW13, SW46 and SW47 to OFF. These are the same settings as in the [Verifying Installation with SPKCommand](testing-BTP-hw-bm64.md#verifying-installation-with-spkcommand). +After new firmware and EEPROM are installed, make sure JP33 jumper is removed and SW9 positions 1, and 2 are both OFF. Set all positions of SW13, SW46 and SW47 to OFF; the same settings as in the [verifying installation with SPKCommand](#verifying-installation-with-spkcommand). -After settings are verified, simply connect a Micro-B USB cable between P3 (labeled *UART* on the EVB) and the test machine. Optionally, 3.5mm jack headphones or speakers can be connected to P7 (labeled *SPK* on the EVB) for audio output if enabled in the EEPROM. If external speakers are to be used, the board must have the 15V barrel jack for powering the audio amp. +After settings are verified, connect a Micro-B USB cable between P3 (labeled *UART* on the EVB) and the test machine. Optionally, 3.5mm jack headphones or speakers can be connected to P7 (labeled *SPK* on the EVB) for audio output if enabled in the EEPROM. If external speakers are to be used, the board must have the 15V barrel jack for powering the audio amp. -To run BTP using the BM-64-EVB, make sure the software is correctly installed following [Setting up BTP Software](testing-BTP-setup.md#software-setup). Additionally, refer to the -[pairing tests](testing-BTP-tests-pairing.md) and [audio test](testing-BTP-tests-audio.md) for running the tests that are currently supported by BTP for the BM-64-EVB. +To run BTP using the BM-64-EVB, make sure the software is correctly installed following [Setting up BTP Software](testing-btp-setup-software.md). Additionally, refer to the +[pairing tests](testing-BTP-tests-pairing.md) and [audio test](testing-BTP-tests-audio.md) for running the tests supported by BTP for the BM-64-EVB. ## (Optional) Installing Firmware for the PIC Microcontroller -This section will explain how to upload new firmware for the on-board PIC microcontroller. The PIC microcontroller is only used for stand-alone Microchip BM-64-EVB examples (like controlling music with push-buttons) and is not necessary for using the BTP tests. +This section explains how to upload new firmware for the on-board PIC microcontroller. The PIC microcontroller is only used for stand-alone Microchip BM-64-EVB examples (like controlling music with push-buttons) and isn't necessary for using the BTP tests. > [!NOTE] > @@ -159,33 +157,33 @@ This section will explain how to upload new firmware for the on-board PIC microc - For *Device*, select PIC18F85J10 (the product name of the target MCU). - For *Tool*, it should be auto populated by the Snap if plugged into USB. -1. Click *Connect* (if successful, the target device should be found in the output screen). +1. Select *Connect* (if successful, the target device should be found in the output screen). 1. Load the hex file included in the DSPK (found at `DSPK v2.x.y Package\Software\Firmware Image\PIC18 Image`). -1. Most likely, a warning saying debug bits are set will appear after the Hex file is loaded. If so, go to the menu and click *Settings*->*Advanced Mode* and enter the password. -1. After the password is entered (and the hex file is still loaded correctly), click *Program*. -1. After successful programming (checksum should match), click *Disconnect* and remove the Snap. +1. Most likely, a warning saying debug bits are set will appear after the Hex file is loaded. If so, go to the menu and select *Settings*->*Advanced Mode* and enter the password. +1. After the password is entered (and the hex file is still loaded correctly), select *Program*. +1. After successful programming (checksum should match), select *Disconnect* and remove the Snap. 1. **Remove the JP33 jumper** before attempting any other functions. ## Further Help -If after the firmware and EEPROM updates and [Verifying Installation with SPKCommand](testing-BTP-hw-bm64.md#verifying-installation-with-spkcommand) is not successful, this means that UART messages are not being passed between the computer and the BM64. There are a few methods to try to correct the issue. +If [verifying installation with SPKCommand](#verifying-installation-with-spkcommand) isn't successful after the firmware and EEPROM updates, UART messages aren't being passed between the computer and the BM64. There are a few methods for correcting the issue. ### Confirm Setup and Power Cycle -The first common issue is the board is not configured correctly using switches and jumpers for running SPKCommand / BTP. A few key component configurations on the board to check are as follows: +The first common issue is the board isn't configured correctly using switches and jumpers for running SPKCommand / BTP. A few key component configurations on the board to check are as follows: -- SW9: Ensure position 1 and 2 are both set to OFF. +- SW9: Ensure positions 1 and 2 are both set to OFF. - P3: Verify the Micro-B USB is plugged into the *UART* port. - JP33: Verify the jumper is removed. - SW13: Ensure all positions are switched to OFF - SW46: Ensure all positions are switched to OFF (in the direction of the BM64 radio on the board) - SW47: Ensure all positions are switched to OFF (in the direction of the BM64 radio on the board) -After these are verified, unplug, wait at least 10 seconds or longer, and replug the Micro-B USB. Even if the configurations are correct, a power cycle of unpluging and plugging may help. Afterwards, try the [Verifying Installation with SPKCommand](testing-BTP-hw-bm64.md#verifying-installation-with-spkcommand) section again. If this still does not work, continue with the further suggestions below. +After these switches, ports, and jumpers are verified, unplug, wait at least 10 seconds or longer, and replug the Micro-B USB. Even if the configurations are correct, a power cycle of unplugging and plugging may help. If [verifying installation with SPKCommand](#verifying-installation-with-spkcommand) still doesn't work, continue with the following suggestions. ### Using MSPK SPKCommand -Another solution is using a different version of the SPKCommand. To do so, download and extract the MSPK v1.35 BM64 software kit from [**Microchip**](https://www.microchip.com/wwwproducts/en/BM64) on the *Documents/Software Libraries/Firmware* tab. Inside the MSPK v1.35 kit, locate the `SPKCommandSetTool v192.006.exe` tool (found at `BM64 Software & Tools (MSPKv1.35)\Tools\SPK CommandSet Tool`). Run through the same instructions in the [Verifying Installation with SPKCommand](testing-BTP-hw-bm64.md#verifying-installation-with-spkcommand) using the MSPK v1.35 version of the SPKCommand tool. If BM-64-EVB correctly responds using the MSPK v1.35 tool, then the board can be used with BTP. +Another solution is using a different version of the SPKCommand. To do so, download and extract the MSPK v1.35 BM64 software kit from [**Microchip**](https://www.microchip.com/wwwproducts/en/BM64) on the *Documents/Software Libraries/Firmware* tab. Inside the MSPK v1.35 kit, locate the `SPKCommandSetTool v192.006.exe` tool (found at `BM64 Software & Tools (MSPKv1.35)\Tools\SPK CommandSet Tool`). Run through the same instructions in the [verifying installation with SPKCommand](#verifying-installation-with-spkcommand) using the MSPK v1.35 version of the SPKCommand tool. If BM-64-EVB correctly responds using the MSPK v1.35 tool, then the board can be used with BTP. ## Features @@ -195,8 +193,8 @@ Another solution is using a different version of the SPKCommand. To do so, downl - Supports Bluetooth dual-mode (BDR/EDR/BLE) - Supports AAC and SBC codecs - Heavily featured, surface mount module -- Using BM-64-EVB does not require a Traduci +- Using BM-64-EVB doesn't require a Traduci ## Known test failures - With version 1.7.2 both standalone audio tests will fail as will some audio-HID tests due to backend architecture changes. If this breaks you, please file a bug or email btpsupport@microsoft.com + With version 1.7.2, both standalone audio tests fail as do some audio-HID tests due to backend architecture changes. If these architecture changes break you, file a bug or email btpsupport@microsoft.com diff --git a/windows-driver-docs-pr/bluetooth/testing-BTP-hw-human-device-adapter.md b/windows-driver-docs-pr/bluetooth/testing-BTP-hw-human-device-adapter.md index 2a2c496863..79534567c5 100644 --- a/windows-driver-docs-pr/bluetooth/testing-BTP-hw-human-device-adapter.md +++ b/windows-driver-docs-pr/bluetooth/testing-BTP-hw-human-device-adapter.md @@ -1,20 +1,20 @@ --- title: Microsoft Bluetooth Test Platform - Human Device Adapter description: Bluetooth Test Platform (BTP) Human Device Adapter (HDA) Setup and Pairing -ms.date: 11/13/2020 +ms.date: 04/11/2023 --- # Human Device Adapter -The Human Device Adapter (HDA) is a do-it-yourself way to manually interact with [Bluetooth Test Platform (BTP)](testing-BTP-Overview.md), allowing use of devices with BTP that have not yet been automated. For example, the HDA would make it possible to interact with a purchased headset that otherwise has no clear way to connect to BTP. The HDA enables manual user testing between a Windows Device and your prototyping hardware without the use of external hardware, such as Traduci. As such, all that is required to set up is a PC that supports Bluetooth and your own test device. +The Human Device Adapter (HDA) is a do-it-yourself way to manually interact with [Bluetooth Test Platform (BTP)](testing-BTP-Overview.md), allowing use of devices with BTP that haven't yet been automated. For example, the HDA would make it possible to interact with a purchased headset that otherwise has no clear way to connect to BTP. The HDA enables manual user testing between a Windows Device and your prototyping hardware without the use of external hardware, such as Traduci. As such, all that is required to set up is a PC that supports Bluetooth and your own test device. ## HDA set-up -Install the software as described in [BTP Software Setup](testing-BTP-setup.md#software-setup) to support the HDA. +Install the software as described in [BTP Software Setup](testing-btp-setup-software.md) to support the HDA. ## HDA configuration file -Create a configuration file as below named after your test device, for example: *mytestdevice.txt*. Note that the filename and extension are not important. +Create a configuration file named after your test device, for example: *mytestdevice.txt*. The filename and extension aren't important. The configuration file should contain the following information: ```console name=myTestDevice @@ -24,7 +24,7 @@ br_address=B4:F1:DA:96:C0:A4 ## HDA pairing tests -Navigate to the folder where the BTP software package was extracted, typically `C:\BTP`. The scripts referenced below will be in a subfolder of the package directory. Run the appropriate script for the desired command environment: +Navigate to the folder where the BTP software package was extracted, typically `C:\BTP`. The scripts are in a subfolder of the package directory. Run the appropriate script for the desired command environment: | Command environment | Script | | --- | --- | @@ -35,7 +35,7 @@ The optional parameter `-VerboseLogs` can be added to provide a more verbose out ## HDA manual pairing -1. The script will respond as below and ask if the device has been paired before. If 'y' is entered it will delete the pairing; if 'n' is entered the process will continue with no action. +1. The script asks if the device has been paired before. If you respond with **y**, the script deletes the pairing. If you respond with **n**, the process continues with no action. ```console Verify: SUCCEEDED(WEX::TestExecution::RuntimeParameters::TryGetValue(deviceParameterName.c_str(), deviceParametersStr)): Getting required runtime parameter 'central' @@ -50,7 +50,7 @@ The optional parameter `-VerboseLogs` can be added to provide a more verbose out Enter (y/n): y ``` - Below is an example of the HDA deleting the pairing. It will prompt also delete any pairing information on the device (here named “MyTestDevice”). Press any key to continue once any pairing information has been deleted. + The following example shows the HDA deleting the pairing. It also prompts you to delete any pairing information on the device (here named "MyTestDevice"). Press any key to continue once any pairing information has been deleted. ```console [BluetoothTestHelpers::Pairing::Unpair]: Unpairing device with address D83BBFAC35607 Public from the device with address D83BBFAC35607 Public @@ -58,7 +58,7 @@ The optional parameter `-VerboseLogs` can be added to provide a more verbose out Press any key to continue ``` -2. The script then begins the pairing process by running checks, then prompting the user to enter their device (here named “MyTestDevice”) into “*Band* Pairing Mode”. Press any key to continue once this has been done. +2. The script then begins the pairing process by running checks, then prompting the user to enter their device (here named "MyTestDevice") into "*Band* Pairing Mode". After putting the device in pairing mode, press any key to continue. ```console StartGroup: BluetoothTests::TaefPairingTests::OutgoingJustWorksPairingTest @@ -71,7 +71,7 @@ The optional parameter `-VerboseLogs` can be added to provide a more verbose out Press any key to continue . . . ``` -3. The script will then initiate pairing. If pairing was successful the output will look exactly as below. Respond to any notifications on the device or on the test PC to confirm and finish pairing. The test then prompts to take the device out of pairing mode. Press any key to continue once this has been done. +3. The script initiates pairing. If pairing is successful, you see the following the output. Respond to any notifications on the device or on the test PC to confirm and finish pairing. The test then prompts you to take the device out of pairing mode. After you to take the device out of pairing mode, press any key to continue. ```console [BluetoothTestHelpers::Pairing::Pair]: Initiating pairing request from device with address D83BBFAC35607 to device with address B4F1DA96C0A4 @@ -84,7 +84,7 @@ The optional parameter `-VerboseLogs` can be added to provide a more verbose out Press any key to continue . . . ``` -4. After pairing is complete the script continues onto the tests available in the test suite. Documentation on available tests and how to run them can be found in [Currently supported BTP tests](testing-BTP-Tests.md) +4. After pairing is complete, the script continues onto the tests available in the test suite. Documentation on available tests and how to run them can be found in [Currently supported BTP tests](testing-BTP-Tests.md) ## HDA log capture @@ -94,7 +94,7 @@ If problems are encountered Bluetooth logs can be captured Bluetooth logs by fol [Bluetooth Test Platform Homepage](testing-BTP-Overview.md) -[Bluetooth Test Platform Software Setup](testing-BTP-setup.md#software-setup) +[Bluetooth Test Platform Software Setup](testing-btp-setup-software.md) [Bluetooth Test Platform Available Tests](testing-btp-tests.md) diff --git a/windows-driver-docs-pr/bluetooth/testing-BTP-setup-package.md b/windows-driver-docs-pr/bluetooth/testing-BTP-setup-package.md index 162f7f891a..8708c1e977 100644 --- a/windows-driver-docs-pr/bluetooth/testing-BTP-setup-package.md +++ b/windows-driver-docs-pr/bluetooth/testing-BTP-setup-package.md @@ -16,14 +16,15 @@ Click the following button to download the latest version. > The installer should be run on the machine that will be executing the tests. After installation, do not copy, move or delete files. If you have a problem with your installation, use Windows "Add or Remove Programs" to completely uninstall BTP. Then do a clean install with the msi. > [!div class="nextstepaction"] -> [Download the current release of BTP](https://download.microsoft.com/download/e/e/e/eeed3cd5-bdbd-47db-9b8e-ca9d2df2cd29/BluetoothTestPlatformPack-1.12.2.msi) +> [Download the current release of BTP](https://download.microsoft.com/download/e/e/e/eeed3cd5-bdbd-47db-9b8e-ca9d2df2cd29/BluetoothTestPlatformPack-1.14.0.msi) ## Version updates | Version | Changes | | --- | --- | +| 1.14.0 | - Added audio tests that can use a custom audio file for playback instead of a generated test tone.
- Fixed an issue that caused unpairing the Bluefruit Feather to fail for some central devices.
- Improved reliability of the Traduci audio analyzer in tests.
- Several other fixes and improvements to test reliability. | 1.12.2 | - Added support for the BM62 radio.
- Added explicit firmware version checks for ESP32 Wi-Fi.
- Other Wi-Fi Co-existence fixes and improvements to test reliability. -| 1.11.1 | - Fixed crash when running standby HID power tests without an installed virtual power button.
- Added explicit firmware version checks for Bluefruit Feather.
- Several other fixes and improvements to test reliability. | +| 1.11.1 | - Fixed crash when running standby HID power tests without an installed virtual power button.
- Added explicit firmware version checks for Bluefruit Feather.
- Several other fixes and improvements to test reliability. | | 1.10.1 | - Added power state HID tests.
- Several other fixes and improvements to test reliability. | | 1.9.0 | - Improved support for BTP devices using custom DLL plugins.
- Fixed an issue affecting the audio mute/unmute tests in certain Windows builds.
- Several other fixes and improvements to test reliability. | | 1.8.0 | - Added Wi-Fi with Bluetooth audio and HID co-existence tests.
- Added mute and unmute audio tests.
- Added option to record audio played during tests to a local file.
- Fixed issue that could cause the Bluefruit Feather to incorrectly report its Bluetooth address.
- Fixed issue with running current audio tests on older Windows builds.
- Several other fixes and improvements to test reliability. | diff --git a/windows-driver-docs-pr/bluetooth/testing-BTP-setup.md b/windows-driver-docs-pr/bluetooth/testing-BTP-setup.md deleted file mode 100644 index 3ef09c48b2..0000000000 --- a/windows-driver-docs-pr/bluetooth/testing-BTP-setup.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Microsoft Bluetooth Test Platform setup -description: How to set up the Microsoft Bluetooth Test Platform -ms.date: 05/13/2022 ---- - -# Setting up the Bluetooth Test Platform (BTP) - -## Hardware setup - -### Connecting Traduci to the PC - -Using the supplied USB A-to-B cable, plug the Traduci into a USB port on the system under test (SUT). Performance is best if the Traduci is plugged directly into an A port on the PC and the Traduci is powered by a [9v, 2A power adapter](https://www.digikey.com/product-detail/en/qualtek/QFWB-18-9-US01/Q1181-ND/8260129) through the barrel connector to the right of the USB connector. Do not connect the Traduci to a USB hub. - -:::image type="content" source="images/Traduci_USBPortSidejpg.jpg" alt-text="An angled side-view of the Traduci circuit board showing USB and power ports."::: - -### Connecting peripherals to the Traduci - -The Traduci has four 12-pin ports (labeled JA, JB, JC, JD) used for test peripherals. - -:::image type="content" source="images/Traduci_12PinPortSide.jpg" alt-text="Traduci showing USB and power ports."::: - -To plug a peripheral device into a port on the Traduci, orient the Traduci so that LEDs and buttons are face up. Next orient the device sled such that the printed label on the device containing the MAC address and any switches are face up. Keeping this orientation, plug the peripheral device in the appropriate 12-pin port. - -> [!NOTE] -> Some peripherals may only plug into certain ports. Please refer to the [supported hardware page](testing-BTP-hw.md) for more information. - -:::image type="content" source="images/Traduci_and_DigilentRN42.jpg" alt-text="Traduci with peripheral plugged in."::: - -## Software Setup - -1. Download the [BTP setup package](testing-BTP-setup-package.md), which will install all required files to the `C:\BTP` directory. - -2. Ensure [Secure boot](/windows-hardware/design/device-experiences/oem-secure-boot) is **disabled**. - -3. Ensure BitLocker is **disabled**. - -4. Ensure the Traduci board is plugged into the SUT. - -5. From an elevated command line on the SUT, navigate to the `C:\BTP` directory and run `ConfigureMachineForBTP.bat` to configure the test machine. A reboot may be required. - -6. Refer to [BTP tests](testing-BTP-Tests.md) for running test scripts in the package. - -## Known issues - -- Power: Intermittent failures may be seen if VCC is not able to supply a steady 5V. In these cases use a 9V AC-DC barrel adapter. These issues are more common during tests utilizing more than 1 device. diff --git a/windows-driver-docs-pr/bluetooth/testing-BTP-tests-audio-hid.md b/windows-driver-docs-pr/bluetooth/testing-BTP-tests-audio-hid.md index 6925114392..ac72aff709 100644 --- a/windows-driver-docs-pr/bluetooth/testing-BTP-tests-audio-hid.md +++ b/windows-driver-docs-pr/bluetooth/testing-BTP-tests-audio-hid.md @@ -1,18 +1,18 @@ --- title: Microsoft Bluetooth Test Platform - Audio and HID scenario tests -description: Bluetooth Test Platform (BTP) Audio and HID Scenario tests. -ms.date: 05/05/2022 +description: Bluetooth Test Platform (BTP) audio and HID scenario tests. +ms.date: 04/11/2023 --- -# BTP Audio and HID Scenario Tests +# BTP audio and HID scenario tests The BTP audio and HID tests verify the ability of the local system to pair with both a HID and an audio device and use these two devices simultaneously. ## Setting Up -When using a Pmod device with the Traduci, first check that the green power indicator, an optional yellow test LED, and 3 orange LEDs on the Traduci are on. Confirm that the SUT's Bluetooth radio is powered on and that the appropriate device(s) are correctly plugged in to the Traduci. Currently the RN52 device can **only** be plugged into JA. Similarly the Bluefruit device can **only** be plugged into JC. More detailed information on setting up can be found at [Setting up BTP](testing-BTP-setup.md). +Before using a Pmod device with the Traduci, check that the green power indicator, an optional yellow test LED, and 3 orange LEDs on the Traduci are on. Confirm that the SUT's Bluetooth radio is powered on and that the appropriate device(s) are correctly plugged in to the Traduci. Currently the RN52 device can **only** be plugged into JA. Similarly the Bluefruit device can **only** be plugged into JC. More detailed information on setting up can be found at [BTP overview](testing-btp-overview.md). -When using the BM-64-EVB, two red LEDs should be on (one of which may turn off after a bit). Confirm the switches, jumpers, and ports are configured for testing as decribed in the [BM-64-EVB board overview](testing-BTP-hw-bm64.md#getting-started). +Two red LEDs on the BM-64-EVB should be on. One of the LEDs may eventually turn off. Confirm the switches, jumpers, and ports are configured for testing as described in the [BM-64-EVB board overview](testing-BTP-hw-bm64.md#getting-started). Features and purchasing information for supported devices can be found at [Supported BTP Hardware](testing-BTP-hw.md). @@ -25,7 +25,7 @@ Features and purchasing information for supported devices can be found at [Suppo ## Running the Audio and HID Scenario Tests -Navigate to the folder where the BTP package was extracted. It will typically be under `C:\BTP`. In a folder named after the version of the package, you will find the scripts referenced below. Then run either: +Navigate to the folder where the BTP package was extracted. It's typically located under `C:\BTP`. In a folder named after the version of the package, you'll find the following scripts. Run either: - `RunAudioHidScenarioTests.bat